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Preface 

Note that while Athena is used for the examples in this book, the techniques 
described are equally applicable to and provide a good introduction to pro- 
gramming with any other widget set based on Xt, such as Motif or Athena. It 
is not difficult to convert an application between any of the widget sets listed 
above, since all of them use the same Xt Intrinsics programming interface. 
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Preface 

This book describes how to write X Window System programs using the Xt Intrinsics library 
(or simply Xt). Xt is a standard established by the X Consortium that provides an object- 
oriented programming style in the C language. 

The Athena widget set library provides user-interface objects to be used with Xt. Athena is 
maintained by the X Consortium, but is not an X Consortium standard. However, it is widely 
available and fre so that it is popular for use in public-domain and freely available pro- 
grams. This book primarily describes the Xt Intrinsics, but it also provides an introduction to 
Athena and uses Athena for many of the examples. 

The Xt Intrinsics together with a second library such as Athena are collectively called the X 
Toolkit. 

Summary of Contents 

The discussion of the X Toolkit is divided into three volumes: Volumes Four, Five, and Six of 
the X Window System Series available from O'Reilly & Associates, Inc. Volume Six is only 
for Motif programmers." 
This is Volume Four, X Toolkit lntrinsics Programming Manual, Standard Edition. It pro- 
vides an explanation of the X Toolkit, including tutorial material and numerous programming 
examples. Arranged by task or topic, each chapter brings together a group of Xt functions, 
describes the conceptual foundation on which they are based, and illustrates how they are 
most often used in writing applications. This volume is structured to be useful as a tutorial 
and also as a task-oriented reference. 
Volume Five, X Toolkit lntrinsics Reference Manual, includes reference pages for each of the 
Xt functions, as well as for the widget classes defined by Xt, organized alphabetically for 
ease of reference; a permuted index; and numerous appendices and quick reference aids. 
The two volumes are designed to be used together. To get the most out of the examples in 
Volume Four, you will need the exact calling sequences of each function from Volume Five. 
To understand fully how to use each of the functions described in Volume Five, all but the 
most experienced Toolkit "hacker" will need the explanation and examples in Volume Four. 

" In the summer of 1993, Volume 6 will be split into two volumes, Volume Six A, Motif Programming Manual, and 
Volume Six B, Motif Reference Manual. 
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Volumes Four and Five include material from the original Toolkit documentation provided 
by MIT, though in Volume Four this material is mostly limited to the appendices. We have 
done our best to incorporate all the useful information from the MIT documentation, to reor- 
ganize and present it in a more useful form, and to supplement it with conceptual material, 
tutorials, reference aids, and examples. In other words, this manual is not only a replacement 
but is a superset of the MIT documentation. 

Each reference page in Volume Five includes a detailed description of the routine similar to 
that found in the Xt specification (X Toolkit Intrinsics Language Interface), plus in many 
cases additional text that clarifies ambiguities and describes the context in which the routine 
would be used. We have also added the definitions of structures and symbolic constants used 
as arguments or returned values by the function, as well as cross-references to related refer- 
ence pages and to where additional information can be found in Volume Four. 

Assumptions 

This book makes no assumptions about the reader's knowledge of object-oriented program- 
ming or the X Window System. Readers should be proficient in the C programming lan- 
guage, although examples are provided for infrequently used features of the language that are 
necessary or useful when programming with the X Toolkit. In addition, general familiarity 
with the principles of raster graphics will be helpful. 

However, even though the Toolkit is intended to hide the low-level X interface provided by 
Xlib, there are times in writing applications or widgets when Xlib functions will be necessary 
because no Xt feature exists to do the same thing. This book describes the most common 
occasions for using Xlib, but does not provide a reference to the particular functions 
involved. Additional documentation on Xlib, such as that provided by Volume One, Xlib 
Programming Manual, and Volume Two, Xlib Reference Manual, will be indispensable. 

Related Documents 

Several other books and a journal on the X Window System are available from O'Reilly & 

Associates, Inc.: 
Volume Zero 
Volume One 
Volume Two 
Volume Three 

Volume Five 
Volume Six A 
Volume Six B 

X Protocol Reference Manual 
Xlib Programming Manual 
Xlib Reference Manual 
X Window System User's Guide, Motif Edition and standard 
edition 
X Toolkit Intrinsics Reference Manual 
Motif Programming Manual (Spring, 1993) 
Motif Reference Manual (Spring, 1993) 
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Volume Seven XView Programming Manual 
Volume Eight X Window System Administrator's Guide 
Quick Reference The X Window System in a Nutshell 
PHIGS in X PHIGS Programming Manual 
PHIGS Reference Manual 
PEXIib PEXIib Programming Manual 
PEXIib Reference Manual 
The X Resource The X Resource is a journal dedicated to X programming. It con- 
tains the latest information about X including articles, papers, and 
documentation. 
The following documents are included on the X 11 source tape (the X distribution from 
MIT): 
X Toolkit Intrinsics--C Language Interface, by Joel McCormack, Paul Asente, 
and Ralph Swick 
X Toolkit Athena Widgets--C Language Interface, by Chris D. Peterson 
Xlib--C Language X Interface, by Jim Gettys, Ron Newman, and Robert 
Scheifler 
The following Nutshell Handbooks published by O'Reilly and Associates, Inc. are use- 
ful when programming in C: 
Checking C Programs with lint, by Ian Darwin 
Managing Projects with make, by Andrew Oram and Steve Talbott 
Using C on the UNIX System, by Dave Curry 
Posix Programmer's Guide, by Donald Lewine 
Practical C Programming, by Steve Oualline 
Power Programming with RPC, by John Bloomer 
Guide to Writing DCE Applications, by John Shirley 

The following is the classic introduction to C programming: 
The C Programming Language, by B. W. Kernighan and D. M. Ritchie 

How to Use This Manual 

Volume Four explains both application programming with widgets and widget programming 
(the design and coding of new widgets). 

The first four chapters treat widgets largely as "black boxes," which is appropriate consider- 
ing the object-oriented philosophy of the Toolkit. These chapters also provide an overview 
of many elements of the X Toolkit, and so are appropriate for all readers. 

Chapter 1 

Introduction to the X Window System, provides a discussion of the context in 
which X programs operate. Programmers who are comfortable programming 
with Xlib can skip Chapter 1. 
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Chapter 2 Introduction to the X Toolkit, describes the conceptual foundations underlying 
Toolkit programming, and shows how to write simple programs that use widg- 
ets from existing widget sets. It introduces such fundamental Toolkit pro- 
gramming concepts as resources, the Translation Manager, callbacks, and 
actions. 
Chapter 3 More Techniques for Using Widgets, describes how to use some of the more 
complex widgets found in applications, including composite widgets, con- 
straint widgets, and popups. It also describes how to define application 
resources and command-line options, and how to hardcode the value of widget 
resources when you create a widget. Finally, it describes how to create multi- 
ple top-level windows, and how to use application contexts to create applica- 
tions that are more portable. 
Chapter 4 An Example Application, describes a complete application, in several itera- 
tions. First, it shows a simple version of the program, a bitmap editor, as it 
would be written assuming the existence of a BitmapEdit widget (which is 
actually developed in Chapter 6). Then, two refined versions are developed, 
each demonstrating additional Toolkit programming techniques. Finally, the 
same application is shown as it would be written if the bitmap editor were 
implemented in an application window rather than with the BitmapEdit 
widget, as it would be written if no BitmapEdit widget existed. 
Chapter 5 The Athena Widget Set, describes and illustrates the widgets available in the 
Athena widget set, and provides some basic programming tips to help you use 
them effectively. As mentioned earlier, this volume does not contain detailed 
reference information on each widget, and it gives examples using only a few 
of the widgets in the Athena widget set. 
The next two chapters describe widget internals and the process of creating new widgets. 
Although this information is not essential for all application programmers, many applications 
require a custom widget to implement their special graphics capabilities. 
Chapter 6 Inside a Widget, describes the code inside a widget. Much of this code is 
common to all widgets. You can think of it as a framework that Xt uses to 
implement a widget's features. After reading this chapter, you should under- 
stand the procedure for creating your own widget around this framework. 
Chapter 7 Basic Widget Methods, describes a widget's initialize, expose, 
set_values, destroy, resize, and query_geometry methods. (A 
widget's methods are internal routines called automatically by Xt to give the 
widget a degree of independence from the application.) The chapter explains 
when Xt calls each method, and describes in detail what should be in each of 
these methods. Among other things, these methods prepare for and do the 
drawing of graphics that appear in a widget. This chapter describes what the 
Toolkit adds to the graphics model provided by Xlib but does not describe in 
detail how to draw using Xlib; this topic is described in Chapters 5, 6, and 7 of 
Volume One, Xlib Programming Manual. 
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Later chapters treat various topics of interest to either application or widget programmers, or 
both. Some of these topics have been introduced in the earlier chapters and are explored 
more completely in the following ones. 
Chapter 8 Events, Translations, and Accelerators, describes the complete syntax of 
translation tables, which allow the user to configure the mapping of event 
sequences into widget actions. It also describes accelerators, a mechanism for 
mapping events in one widget to actions in another. 
Chapter 9 More Input Techniques, describes how to handle events with event handlers 
and how to use information from the event structure inside an event handler or 
action routine. It also describes how to get file, pipe, or socket input, how to 
use timeouts to call a function after a delay or at particular intervals, and how 
to use work procedures to do background processing. Finally, it discusses 
some low-level features of Xt for directly interacting with the event queue. 
Resource Management and Type Conversion, is a more thorough discussion of 
how resources work and how they should be used. This chapter describes in 
detail the resource file format and the rules that govern the precedence of 
resource settings. It also describes how to add your own type converter so that 
you can set application- or widget-specific data through resources. Finally, it 
describes subresources and how to use them. 
Interclient Communications, discusses communication through the X server 
between an application and the window manager, and between two applica- 
tions. The application-window manager communication is performed by code 
in the Shell widget; the application sets shell resources to control this commu- 
nication. Application-application communication is usually done with a pro- 
cess called selections; this form of communication is already implemented in 
most widgets that display text, but you may want to implement it in your own 
custom widgets. Selections can also pass other kinds of data such as graphics. 
Geometry Management, discusses how composite and constraint widgets man- 
age the layout of widgets, and how to write your own simple composite and 
constraint widgets. 
Menus, Gadgets, and Cascaded Popups, describes how menus work and 
describes several ways to create menu widgets. One of these ways involves 
the use of windowless widgets, or gadgets. This chapter also describes how to 
use more advanced features of the Xt pop-up mechanism, including modal 
cascades, to implement cascading pop-up menus. 
Miscellaneous Toolkit Programming Techniques, describes various Xt func- 
tions and techniques that have not been treated elsewhere in the book. These 
include functions for error and warning handling, case conversion, using edi- 
tres, and so on. 
Athena, OPEN LOOK, and Motif, provides a comparison of the widgets avail- 
able in AT&T's OPEN LOOK widget set and OSF's Motif. These widgets are 
contrasted with those in the Athena widget set. 

Chapter 10 

Chapter 11 

Chapter 12 

Chapter 13 

Chapter 14 

Appendix A 
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Obtaining the Example Programs 

The example programs in this book are available electronically in a number of ways: by ftp, 
ftpmail, biotp, and uucp. The cheapest, fastest, and easiest ways are listed first. If you read 
from the top down, the first one that works for you is probably the best. Use ftp if you are 
directly on the Intemet. Use ftpmail if you are not on the Intemet but can send and receive 
electronic mail to intemet sites (this includes CompuServe users). Use BITFTP if you send 
electronic mail via BITNET. Use UUCP if none of the above works. 

FTP 

To use FTP, you need a machine with direct access to the Internet. A sample session is 
shown, with what you should type in boldface. 
% ftp ftp.uu.net 
Connected to ftp.uu.net. 
220 FTP server (Version 6.21 Tue Mar i0 22:09:55 EST 1992) ready. 
Name (ftp.uu.net :kismet) : anonymous 
331 Guest login ok, send domain style e-mail address as password. 
Password: ki smet@ora, corn (use your user name and host here) 
230 Guest login ok, access restrictions apply. 
ftp> cd /published/oreilly/xbook/xt 
250 CWD conmand successful. 
ftp> binary (Very important{ You must specify binary transfer for compressed files ) 
200 Type set to I. 
ftp> get xtprog3, tar. Z 
200 PORT conmnnd successful. 
150 Opening BINARY mode data connection for xtprogs2.tar.Z. 
226 Transfer complete. 
ftp> quit 
221 Goodbye. 
% 
If the file is a compressed tar archive, extract the files from the archive by typing: 
% zcat xtprogs2, tar. Z I tar xf - 
System V systems require the following tar command instead: 
% zcat xtprogs2.tar. Z [ tar xof - 
If zcat is not available on your system, use separate uncompress and tar commands. 
If the file is a compressed shar archive, you can extract the files from the archive by typing: 
% uncompress FILE. shar. Z 
% /bin/sh FILE. shar 
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FTPMAIL 

PTPMAIL is a mail server available to anyone who can send and receive electronic mail to 
and from lnternet sites. This includes most workstations that have an email connection to the 
outside world, and CompuServe users. You do not need to be directly on the Internet. Here's 
how to do it. 
You send mail toftpmail@decwrl.dec.com. In the message body, give the name of the anon- 
ymousftp host and the ftp commands you want to run. The server will run anonymousftp for 
you and mail the files back to you. To get a complete help file, send a message with no sub- 
ject and the single word "help" in the body. The following is an example mail session that 
should get you the examples. This command sends you a listing of the files in the selected 
directory, and the requested examples file. The listing is useful in case there's a later version 
of the examples you're interested in. 
% mail ftpmail@decwrl.dec.com 
Subj ect : 
reply j erry@ora, com (where you want files mailed) 
connect ftp. uu. net 
chdir /published/oreilly/xbook/xt 
dir 
binary 
uuencode (or btoa if you have it) 
get xtprogs2, tar. Z 
quit 
A signature at the end of the message is acceptable as long as it appears after "quit." 
All retrieved files will be split into 60KB chunks and mailed to you. You then remove the 
mail headers and concatenate them into one file, and then uudecode or atob it. Once you've 
got the desired file, follow the directions under FTP to extract the files from the archive. 
VMS, DOS, and Mac versions of uudecode, atob, uncompress, and tar are available. The 
VMS versions are on gatekeeper.dec.com in/archive/pub/VMS. 

BITFTP 

BITPTP is a mail server for BITNET users. You send it electronic mail messages requesting 
files, and it sends you back the files by electronic mail. BITP'YP currently serves only users 
who send it mail from nodes that are directly on BITNET, EARN, or NetNorth. BITPTP is a 
public service of Princeton University. Here's how it works. 

To use BITPTP, send mail containing yourftp commands to BITFTP@PUCC. For a complete 
help file, send HELP as the message body. 

The following is the message body you should send to BITP'YP: 

FTP ftp. uu. net NETDATA 
USER anonymous 
PASS your Internet email address (not your bitnet address) 
CD /published/oreilly/xbook/xt 
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DIR 
BINARY 
GET xtprogs2, tar. Z 
QUIT 
Once you've got the desired file, follow the directions under FFP to extract the files from the 
archive. Since you are probably not on a UNIX system, you may need to get versions of 
uudecode, uncompress, atob, and tar for your system. VMS, DOS, and Mac versions are 
available. The VMS versions are on gatekeeper.dec.com in/archive/pub/VMS. 
Questions about BITFTP can be directed to Melinda Varian, MAINT@PUCC on BITNET. 

UUCP 

UUCP is standard on virtually all UNIX systems, and is available for IBM-compatible PCs and 
Apple Macintoshes. The examples are available by UUCP via modem from UUNET; 
UUNET's connect-time charges apply. 

You can get the examples from UUNET whether you have an account or not. If you or your 
company has an account with UUNET, you will have a system with a direct UUCP connection 
to UUNET. Find that system, and type: 
uucp uunet\ !  /published/ oreilly /xbook/xt /xtprogs2 . tar. Z yourhos.~/yourname/ 

The backslashes can be omitted if you use the Bourne shell (sh) instead of csh. The file 
should appear some time later (up to a day or more) in the directory /usr/spool/uucppub- 
lic/yournatne. If you don't have an account but would like one so that you can get electronic 
mail, then contact UUNET at 703-204-8000. 

If you don't have a UUNET account, you can set up a UUCP connection to UUNET using the 
phone number 1-900-468-7727. As of this writing, the cost is 50 cents per minute. The 
charges will appear on your next telephone bill. The login name is "uucp" with no password. 
For example, an L.sys/Systems entry might look like: 

uunet Any ACU 19200 1-900-468-7727 ogin:--ogin: uucp 

Your entry may vary depending on your UUCP configuration. If you have a PEP-capable 
modem, make sure s50=255s I 11 =30 is set before calling. 
It's a good idea to get the file/published/oreilly/xbook/xt/ls-lR.Z as a short test file containing 
the filenames and sizes of all the files in the directory. 
Once you've got the desired file, follow the directions under FFP to extract the files from the 
archive. 
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Compiling the Example Programs 

Once you've got the examples and unpacked the archive as described previously, you're 
ready to compile them. The easiest way is to use imake, a program supplied with the X I 1 
distribution that generates proper Makefiles on a wide variety of systems, imake uses confi- 
guration files called lmakefiles which are included. If you have imake, you should go to the 
top-level directory containing the examples, and type: 
% make Makefiles 
% make 
All the application-defaults files are in the main examples directory. The application- 
defaults files are not automatically installed in the system application-defaults directory 
(usually/usr/lib/Xll/app-defaults on UNIX systems).1- If you have permission to write to that 
directory, you can copy them there yourself. Or you may set the XAPPLRESDIR environment 
variable to the complete path of the directory where you installed the examples. The value of 
XAPPLRESDIR must end with a / (slash). (Most of the examples will not function properly 
without the application-defaults files.) 
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Introduction to the X Window System 

This chapter introduces many of the most important concepts on which the X 
Window System is based, and describes the environment in which the X 
Toolkit operates. This chapter assumes that you are new to programming 
the X Window System. If you already have some experience programming 
the X Window System, you may wish to skim this chapter for a brief review 
or even begin with Chapter 2. 

In This Chapter: 

The Server and Client ............................................................................ 6 
The Software Hierarchy ......................................................................... 8 
Event-driven Programming .................................................................. 10 
The Window Manager .......................................................................... 11 
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1 
Introduction to the X Window System 

The X Window System (or simply X)I- is a hardware- and operating system-independent win- 
dowing system. It was developed jointly by MIT and Digital Equipment Corporation, and 
has been adopted by the computer industry as a standard for graphics applications. 
X controls a "bit-mapped" display in which each pixel on the screen is individually controll- 
able. This allows applications to draw pictures as well as text. Until recently, individual 
control of screen pixels was widely available only on personal computers (PCs) and high- 
priced technical workstations. Most general-purpose machines were limited to output on 
text-only terminals. X brings a consistent world of graphic output to both PCs and more 
powerful machines. Figure 1-1 compares an X application to an application running on a tra- 
ditional text terminal. 

text terminal 

X window system 

Figure 1-1. An X application, and an application on a traditional text terminal 

fThe name "X Windows" is frowned upon by the developers of X. 
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inside its border. The application or the user can change the dimensions of windows. Figure 
1-3 shows a typical screen with several virtual terminals running. The screen also shows 
some applications, such as xterm, oclock, and xcalc, that run in their own windows 

xterm window 
(typical of 3) 

root window - . - 

Figure 1-3. Screen layout of a typical user's X Window System 

X supports both color and black-and-white displays. 

Many of the above characteristics are also true of several other window systems. What is 
unusual about X is that it is based on a network protocol instead of on system-specific proce- 
dure and system calls. This network protocol enables X to be ported to different computer 
architectures and operating systems; it also allows programs to run on one architecture or 
operating system while displaying on another. Because of its unique design, X can make a 
network of different computers cooperate. For example, a computationally intensive applica- 
tion might run on a supercomputer, but take input from and display output on a workstation 
connected across a local area network. To the user, the application would simply appear to 
be running on the workstation. 

1.1 The Server and Client 

To allow programs to be run on one machine and display on another, X was designed as a net- 
work protocol--a predefined set of requests and replies--between two processes. One of 
these processes is an application program called a client, and the other, the server, controls 
the display hardware, keyboard, and pointer. 

The user sits at the machine running the server. At first, this use of the word "server" may 
seem a little odd, since file and print servers normally are remote machines, but the usage is 
consistent. The local display is accessible to other systems across the network, and for those 
systems the X server does act like other types of server. 
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Personal Computer 

Supercomputer 

Ir 

Local 
Client 

Display Server 

Large Minicomputer 

Figure 1-4. Applications can run on any system across the network 

This use of the network is known as distributed processing. It allows graphic output for pow- 
erful systems that don't have their own built-in graphics facilities. Distributed processing 
can also help solve the problem of unbalanced system loads. When one host machine is over- 
loaded, users running clients on that machine can arrange for some of their clients to run on 
other hosts. Eventually there may be automatic load-balancing applications, but currently 
such remote execution is performed manually. It is not unusual to see users in the X environ- 
ment having several xload load monitor applications running on various systems throughout 
the network but displaying on their screen, so that they can see the balance of loads through- 
out the network. 

Before leaving the subject of servers and clients, we should mention PC servers and X termi- 
nals. Software is available that allows various types of PCs to operate as X servers.'t" X ter- 
minals are special-purpose devices designed to run just an X server, and to connect to remote 
systems over a local area network. PC servers and X terminals are the least expensive way to 
provide an X screen for a user. Since most PCs use single-tasking operating systems, they 
can't run any clients at the same time as the server. Therefore, they too require a network 
adapter to connect to another system where clients are run. 

" Companies such as Graphics Software Systems, Interactive Systems, and Locus Computing offer server implemen- 
tations for IBM-compatible PCs. White Pine Software offers an X server that runs under Multifinder on the Macin- 
tosh. An Amiga server is available from GfxBase/Boing. X terminals are available from Visual Technology, NCR, 
Network Computing Devices (NCD), Tektronix, Graphon Corp, and other companies. The number of X products on 
the market is growing rapidly. 
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Xt is built upon Xlib. The purpose of Xt is to provide an object-oriented layer that supports 
the user-interface abstraction called a widget. A widget is a reusable, configurable piece of 
code that operates independently of the application except through prearranged interactions. 
A widget set is a collection of widgets that provide commonly used user-interface compo- 
nents tied together with a consistent appearance and user interface (also called look and feel). 
Several different widget sets are available from various vendors that are designed to work 
with Xt. The use of widgets separates application code from user-interface code and pro- 
vides ready-to-use user-interface components such as buttons and scrollbars. Xt, widgets, 
and widget sets are described in much more detail in Chapter 2, Introduction to the X Toolkit. 
In this book, we'll refer to the combination of the Xt lntrinsics and one widget set as the X 
Toolkit or just the Toolkit. When referring to the Xt lntrinsics layer alone, we'll use Xt, or the 
Intrinsics. 
Applications often need to call Xlib directly to accomplish certain tasks such as drawing. Xt 
does not provide its own graphics calls, nor does it provide access to every X protocol fea- 
ture. This book describes the features of Xlib that you may need from an Xt application, but 
it will not repeat the detailed description of Xlib programming found in Volume One, Xlib 
Programming Manual. You will find Volume One and Volume Two, Xlib Reference Manual, 
invaluable when you need to make Xlib calls. 
Xlib, Xt, and several widget sets are available on MIT's public software distribution. The 
Motif and OPEN LOOK widget sets are not on the Release 4 or 5 distributions from MIT, but 
they are available for minimal cost from the vendors themselves (OSF, AT&T, or Sun, 
respectively.) The darkly shaded areas of Figure !-5 indicate interfaces that are exclusive 
standards of the X Consortium. That Xlib is an exclusive standard means that computer man- 
ufacturers wishing to comply with the X Consortium standard must offer Xlib and cannot 
offer any other low-level X interface in C. The lightly shaded areas (such as the Xt Intrin- 
sics) are nonexclusive standards--vendors are required t 9 provide Xt but are also allowed to 
provide other toolkit-level layers for the C Language. For example, Sun and AT&T offer Xt, 
but they also offer XView as an alternate C-Language toolkit-level layer. XView was origi- 
nally designed for porting existing SunView TM applications to X, but it can also be used for 
writing new applications. Volume Seven, XView Programming Manual, describes program- 
ming with XView. 
X software is unlike that of many other window systems in that it was designed to provide 
mechanism without mandating any certain style of user interface. In the words of its design- 
ers, X provides "mechanism without policy." The Xlib and Xt layers are standard because 
they can support any kind of interface. It is the widget set that actually imposes user-inter- 
face conventions, and it is this layer for which no standard has yet been considered by the X 
Consortium. However, because there is a strong need in the market for one or two standard 
widget sets that provide consistent appearance and user-interface conventions, it is likely that 
one or two widget sets will emerge as de-facto standards in the near future. 
It is important to note that the X Consortium standards for Xlib and Xt define the program- 
ming interface to each library (often referred to as the Application Programmer's Interface, 
or API), not the underlying code. This means that vendors are allowed to modify or rewrite 
the code to gain the best performance from their particular system, as long as they keep the 
programming interface the same. To you, the application writer and user of the Intrinsics, 
this means that you must always rely on documented behavior if you want your application to 
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run on different systems. You must avoid accessing private structures, because they may be 
different in another vendor's release of the library, or they may be changed in a future release 
of X. 

1.3 Event-driven Programming 

Programming a graphically-based window system is fundamentally different from standard 
procedural programming. In traditional character-based interfaces, once the application 
starts, it is always in control. It knows only what kind of input it will allow, and may define 
exclusive modes to limit that input. For example, the application might ask the user for input 
with a menu, and use the reply to go down a level to a new menu, where the actions that were 
possible at the previous level are no longer available. Or a text editor may operate in one 
mode in which keyboard input is interpreted as editor commands, and another in which it is 
interpreted as data to be stored in an editor buffer. In any case, only keyboard input is 
expected. 
In a window system, by contrast, multiple graphic applications may be running simulta- 
neously. In addition to the keyboard, the user can use the pointer to select data, click on but- 
tons or scrollbars, or change the keyboard focus from one application to another. Except in 
special cases (for example, where a "dialog box" will not relinquish control until the user 
provides some necessary information), applications are modeless--the user can suddenly 
switch from the keyboard to the mouse, or from one application area to another. Further- 
more, as the user moves and resizes windows on the screen, application windows may be 
obscured or redisplayed. The application must be prepared to respond to any one of many 
different events at any time. 
An X event is a data structure sent by the server that describes something that just happened 
that may be of interest to the application. There are two major categories of events: user 
input and window system side effects. For example, the user pressing a keyboard key or 
clicking a mouse button generates an event; a window being moved on the screen also gener- 
ates events--possibly in other applications as well if the movement changes the visible por- 
tions of their windows. It is the server's job to distribute events to the various windows on 
the screen. 
Event-driven window programming reduces modes to a minimum, so that the user does not 
need to navigate a deep menu structure and can perform any action at any time. The user, not 
the application, is in control. The application simply performs some setup and then goes into 
a loop from which application functions may be invoked in any order as events arrive. 
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1.4 The Window Manager 

Because multiple applications can be running simultaneously, rules must exist for arbitrating 
conflicting demands for input. For example, does keyboard input automatically go to which- 
ever window the pointer is in, or must the user explicitly select a window? How does the 
user move or resize windows? 
Unlike most window systems, X itself makes no rules about this kind of thing. Instead, there 
is a special client called the window manager that manages the positions and sizes of the 
main windows of applications on a server's display. In Motif, this client is mwm. The win- 
dow manager is just another client, but by convention it is given special responsibility to 
mediate competing demands for the physical resources of a display, including screen space, 
color resources, and the keyboard. The window manager allows the user to move windows 
around on the screen, resize them, and usually start new applications. The window manager 
also defines much of the visible behavior of the window system, such as whether windows 
are allowed to overlap or are forced to tile (side by side), and whether the keyboard focus 
simply follows the pointer from one window to the next window, or whether the user must 
click a pointer button in a window to change the keyboard focus. 
Applications are required to give the window manager certain information to help it mediate 
competing demands for screen space or other resources. For example, an application speci- 
fies its preferred size and size increments. These are known as window manager hints 
because the window manager is not required to honor them. The Toolkit provides an easy 
way for applications to set window manager hints. 
The conventions for interaction with the window manager and with other clients have been 
standardized by the X Consortium in a manual called the Inter-Client Communication Con- 
ventions Manual (ICCCM for short). The ICCCM defines basic policy intentionally omitted 
from X itself, such as the rules for transferring selections of data between applications, for 
transferring keyboard focus, for installing colormaps, and so on. 
As long as applications and window managers follow the conventions set out in the ICCCM, 
applications created with different toolkits will be able to coexist and work together on the 
same server. Toolkit applications should be immune to the effects of changes from earlier 
conventions because the conventions are implemented by code hidden in a standard widget 
called Shell. However, you should be aware that some older applications and window man- 
agers do not play by the current rules. 
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1.5 Extensions to X 

X is also extensible. The code includes a defined mechanism for incorporating extensions, so 
that vendors aren't forced to modify the existing system in incompatible ways when adding 
features. An extension requires an additional piece of software on the server side and an 
additional library at the same level as Xlib on the client side. After an initial query to see 
whether the server portion of the extension software is installed, these extensions are used 
just as Xlib routines and perform at the same level. 
As time goes on, some extensions will become a basic part of what is called "X," and will 
become X Consortium standards themselves. For example, as of Release 5 the X Consortium 
has standardized three extensions: the non-rectangular window Shape extension, the X Input 
extension for supporting input devices other than the keyboard and mouse, and PEX for 3-D 
graphics. The only one of these libraries that is widely available on X servers, and is com- 
monly used in conjunction with Xt, is the Shape extension. The C programming library used 
to access the Shape extension is -1Xext. 
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2 

Introduction to the X Toolkit 

This chapter provides a conceptual introduction to the X Toolkit (including the 
Athena widget set), followed by a practical tutorial that starts with the most 
fundamental toolkit program, a "hello world" type application consisting of 
only a single widget. This application is successively refined until the major 
elements of any X Toolkit program have been introduced. 

In This Chapter: 
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Two commercial widget sets that are easily available and quite complete are OSF's Motif 
and AT&T's OPEN LOOK Intrinsics Toolkit (normally called OLIT). Both Motif and OPEN 
LOOK contain menus, scrollbars, command buttons, dialog boxes, and a wide variety of com- 
posite widgets. Both have an attractive appearance and consistent, well defined user- 
interface conventions. Each comes with a style guide that contains suggestions for designing 
applications to blend in well with other applications using that widget set. 
To highlight some of the added value provided by a commercial widget set such as Motif, 
Figure 2-3 shows the same hypothetical application constructed with Motif widgets, and with 
a titlebar provided by the mwm window manager. 
As you can see, Motif has a distinctive appearance, using shadowed outlines to simulate a 
3-D appearance (buttons appear to be pushed in when you click on them, and so forth). What 
is more important, Motif has conventions about the use of its widgets that lead to a consistent 
look among all applications using Motif. The OSF/MotifStyle Guide contains recommenda- 
tions for application design and layout, and whenever possible, these recommendations are 
actually embodied in the design of the widget set. For example, the Motif MainWindow 
widget provides a menubar at the top of the application, which can contain titles for standard 
"pulldown" menus for file manipulation and on-line help, as well as for various application 
functions. 
Motif also provides many more widgets than Athena, making it easy to create control areas 
such as radio boxes (groups of buttons, of which only one can be chosen at a time) or check 
boxes (groups of buttons that may be set independently of each other, say for making applica- 
tion configuration choices.) There are also convenience functions for creating many common 
combinations of widgets. 
The mwm window manager provides similar functions to twin, but also always provides sup- 
port for a help feature (invoked by clicking on the box in the upper right corner of the 
titlebar). 
The Motif widgets also support some advanced features for internationalization such as lan- 
guage-independent "'compound strings," keyboard traversal (moving between widgets with 
keyboard keys rather than a mouse--this is very helpful for the design of data-entry applica- 
tions), and mnemonic key equivalents for invoking menu commands. 
This book provides examples that use the Athena widget set. However, unless otherwise 
noted the techniques described in this book for using, modifying, and creating widgets are 
defined by Xt, and therefore are the same regardless of which widget set you use. You can 
use many of the same techniques to create applications using AT&T's OPEN LOOK widget 
set, or using the Motif widgets. 
An important reminder here is that this is a book on the Xt Intrinsics, not primarily on 
Athena. Athena-specific features are introduced in Chapter 5 and in a few other places, but 
not described in minute detail. Moreover, Athena-specific features are carefully dis- 
tinguished from the basic Xt features, to make it is easier to know what features are portable 
between widget sets. 
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2.1.2 Widget Classes and Instances 

A widget set defines classes of widgets. Label is a class of widget, as are Command, Text, 
Scrollbar, and the various widgets shown in our hypothetical application.'l" Each time you 
create a widget, you create an instance of one of these predefined classes. For example, you 
might create several Command widgets, each with a unique name, containing a unique text 
label, and each invoking different application code when it is clicked on. All these widgets 
would be of class Command, but they usually have different string names such as "quit", 
"run", and "stop". They would have similar characteristics, but they would not necessarily 
look or act exactly the same since each could have been configured differently. 

A widget class has certain fixed features which are common to all instances of that class, and 
certain characteristics which can be changed from one instance to the next. 

How you view a class depends on whether you are using existing widget classes or are also 
writing new ones. Eventually you will thoroughly understand both these views of a class, 
since you will be competent in both using and writing widgets. For the first four chapters of 
this book, we will concentrate on the widget user's point of view. Both views are introduced 
here because we don't want to mislead you by telling you only the widget user's view, half 
the story of what a class is. 

For a user of existing widget classes (a widget set), a widget class is a black box that has cer- 
tain fixed features and certain configurable features, both of which are documented on the 
widget class's reference page. You need not know anything about how a class is imple- 
mented in Xt. You know that when you create an instance of that widget class, the instance 
will have the documented fixed features and that you can set the configurable features. A 
user of existing widget classes is most interested in the configurable features, since setting 
these is a big part of programming an Xt application. Each configurable feature is called a 
resource. Resources are more fully introduced in the next section. 

If you are writing a widget class, or if you have written one and see things from that perspec- 
tive, a class seems slightly different. To you, a widget class is a set of files in which the 
widget class is implemented. The widget class is no longer a black box--it is an open box. 
Knowing what widget class code looks like, you know that its fixed features and its configur- 
able features are implemented in distinct sections of the code. You know that each resource 
is actually represented by a field in a structure. You know that each class has a structure (the 
class structure) that contains all the fixed features (both code and data) of that class. Even 
though you don't necessarily have access to the source code for a widget class, your defini- 
tion of a class is based on how that class is implemented. 

Figure 2-3 illustrates these two ways of viewing what a class is. 

"l'The names of all Motif widget classes actually begin with Xm. However, to make the text more readable, we have 
omitted the Xm prefix when referring to these widgets, except in examples and discussions of code where the prefix 
must actually be used. 
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The widget user's view 

Documented Inputs ' ..., Documented Outputs 
.. 

(implementation hidden) 

Documented Inputs :.!. ii. I 
I 

The widget writer's view 

.c file .h file P.h file 
(implementation exposed) 

Documented Outputs 

Figure 2-3. Two ways to think about a class 

These two views of a class take on special relevance when looking at a characteristic of the 
Toolkit called class inheritance. Widget features and characteristics can be inherited from 
other, more basic classes of widgets. To a widget user. class inheritance is important only 
because it means that the resources (configurable features) of a widget class are defined not 
only by the class itself but also by the classes from which the class inherits features, called its 
superclasses. When you look up a widget class's features on its reference page, either all its 
superclass's resources will be described, or you will have to look up its superclass and look 
on that page also, and continue up the class inheritance hierarchy to the most basic widget, in 
order to get a complete list of its capabilities. This sounds difficult, but in reality you get to 
know the features of the most basic classes by heart, and the classes are not deeply nested. 
From the widget writer's point of view, inheritance means that a new class of widget needs to 
define only its own unique features, and need not re-implement features common to all widg- 
ets, or already implemented by an existing superclass. All classes exist in a single-inheri- 
tance hierarchy that defines which other classes each class inherits features. (Note that the 
class hierarchy is completely different from the parent-child relationship of widget instances 
you create in an application. The class hierarchy of a particular widget set is fixed by the cre- 
ators of the widget set, while the instance hierarchy is different in every application, and is 
determined solely by the writer of the application. The instance hierarchy specifies which 
widgets contain which other widgets on the screen.) 
Figure 2-4 shows the class inheritance hierarchy for the Athena widget set. Classes defined 
by Xt (which are the same for all widget sets) are shaded gray.'l" This section describes the Xt 
classes, as well as the most basic Athena classes, in order to clarify the concept of classing as 
-I-Note that the X Toolkit supports only single inheritance. That is, characteristics can be inherited directly from only 
one superclass (though that superclass may itself have inherited characteristics from prior superclasses. A widget 
class can inherit only from the classes on a direct path upward from the class to Core. 
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the desired behavior. For example, one would create a subclass of Core in order to develop a 
custom graphics window. 

As long as appropriate widget classes are available, the application programmer needs to 
know little or nothing about widget internals. In fact, even if widget internals are known, it is 
unwise to depend on knowledge of them. Widgets should be treated as black boxes with doc- 
umented inputs and outputs. If only these documented interfaces are used, the widget inter- 
nals can be modified without affecting the application, and the application can be modified 
without affecting the widget. 

2.1.3 

Widget Configurability with Resources 

To serve their purpose as reusable user-interface components, widgets must be highly confi- 
gurable. For example, an application programmer must be able to define not only a separate 
label for each Command widget, but also the application function that is invoked when the 
button is clicked. The programmer will also want to let the user define additional attributes 
such as font and color. 

To support this degree of configurability, widget classes can declare variables as named 
resources of the widget. The application can pass the value of widget resources as arguments 
to the call to create a widget instance, or can set them after creation using the Intrinsics call 
XtSetValues (). Even before that, though, as an application starts up, a part of Xlib 
called the resource manager reads configuration settings placed in a series of ASCII files by 
the user and/or the application developer, and Xt automatically uses this information to con- 
figure the widgets in the application. The collection of resource name/value pairs contained 
in the various resource files and set directly by the application is collectively referred to as 
the resource database. 

Figure 2-5 shows several Athena Label widgets configured with different resource settings, to 
show you how radically the appearance of even such a simple widget can be altered. Note 
that a widget's input characteristics can also be configured (although the Label class has no 
input characteristics to configure). 

i [ ]-'4,,[:]l[,l'Jd. _ 
I Hello, W'orld! 1 

Figure 2-5. Several Athena Label widgets configured using resources 
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The resource manager provides a flexible mechanism for generalizing the behavior of widg- 
ets. The application developer can "'hardcode'" the value of those resources that must not be 
changed because they could cripple the application (as when changing the label of the Quit 
widget to Save), and can establish reasonable defaults for other resources, so that the user can 
configure all nonessential aspects of an application's look and feel. 
Note that the term "resource" is used somewhat ambiguously in X. First, in the original doc- 
umentation for Xlib and the X Protocol, various data structures that are maintained by the 
server and identified to clients only by an integer ID are referred to as resources. These data 
structures include windows, colormaps, fonts, and so forth. In this series, these are normally 
called server resources where there is possible confusion. 
Second, the term is commonly used to refer both to a widget variable publicly declared as a 
widget resource, and to the name/value pairs in the resource database. In this book, we will 
use the term resource to refer to the actual variable and its current value in a widget instance, 
and the term resource setting to refer to a name/value pair in the database. The two are 
closely related, but may not be identical. For example, separate settings for the same 
resource may be requested in an app-defaults file and in an individual's user-preference file.l" 
Furthermore, the value of a resource may be set on the fly by a call to XtSetValues ( ), but 
this value is never saved in the resource database. (This value can be retrieved from within a 
widget or application by a call to XtGetValues ( ) .) 

2.1.4 

Widget Independence 

Each widget operates, to a large degree, independently of the application. Xt dispatches 
events to a widget, which performs the appropriate actions according to the design of its 
class, without application help. For example, widgets redraw themselves automatically when 
they become exposed after being covered by another window.:]: Widgets also handle the con- 
sequences when the values of their resources are changed. An instance of Label, for 
example, does not depend on the application that created it to determine its size. By default, 
Label will choose a size large enough to accommodate the current string in the current font. 
If the application changes the text or font in the l.abel widget with a call to XtSet- 
Values (), the Label widget itself will attempt to keep its own window large enough to 
accommodate the current string. (Of course, if necessary, the application can also explicitly 
choose the Label widget's size.) When the application tells a Label widget what font to dis- 
play its string in, the widget knows how to load a new font, recalculate its own size, and 
redraw its string--the application doesn't have to micro-manage any of this. The application 
simply sets the font resource of the widget, and the widget does the rest. 

There are several possible sources of resource settings. If two or more contain resource settings for the same re- 
source of the same widget, which will actually take effect is determined by rules of precedence that are described 
(along with the various sources of resource settings) in Chapter 10, Resource Management and Type Conversion. 
 Redrawing is necessary because the contents of X windows are maintained by the X server only while they are visi- 
ble. When one window is obscured by another, the contents of the obscured area of one of the windows is lost and 
must be redrawn when it later becomes exposed. X clients are responsible for redrawing the contents of their win- 
dows when this happens. Fortunately, Xt automatically redraws correctly written widgets at the appropriate times so 
that your application doesn't have to worry about this. 
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Figure 2-6 and Figure 2-7 illustrate how a widget operates independently of the application 
and how Xt:Set:Val ues ( ) lets the application set how a widget operates itself. 

Server 

Expose and user events 

Network 

Drawing requests 

Widget 

[_..Application Code 

Xt 
Intrinsics 
Routines 

Widgets operate independently of the application... 

Figure 2-6. Widgets operate independently of the application 
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Network 

' Widget 
XtSetValues 
Application Code 
...... 

Xt 
Intrlnsics 
Routines 

...but the appfication can change various characteristics of the widget with XtSetValues 

Figure 2-7. XtSetValues lets the application set how a widget will operate itself 
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2.1.6.2 Methods 

2.1.6.3 

2.1.6.4 

What is called a method in traditional OOP is either a method or an action in Xt. In Xt, 
methods are a set of functions that are fixed for a particular class, triggered in fixed ways 
usually in response to Xt function calls made by the application (with one special case, the 
extz, ose method, triggered directly by the Extz, ose event). A widget's methods supply its 
most basic functions, such as the code needed to create a window, or to redraw itself. 
Actions, on the other hand, are called in response to the events specified in a translation table, 
and thus the events that trigger actions are user configurable. Actions supply most of the fea- 
tures of widgets, and these features can be added to or replaced by the application, as demon- 
strated in Sections 4.4 and 4.6. 

From the widget writer's point of view, each method is just a function whose pointer has a 
place in the class structure. Each method has particular responsibilities in managing the 
basic functions necessary for a widget to be a widget. For example, every widget class must 
have a method that responds to calls to Xt:Set:Values ( ). What each of the vital methods 
must do is described in Chapter 7, Basic Widget Methods. Each method has different argu- 
ments and returned values. 

Every action, on the other hand, has the same set of arguments. Actions generally perform 
the features of the widget that are triggered by events. You could say that actions are the 
widget's occupation: it needs them to do anything useful but does not need them to exist. 

Messages 

In pure OOP, input to objects and communication between them are called messages. In Xt, 
however, the forms of communication are function calls, events, actions, and callbacks. As 
you have seen, applications can communicate with widgets using function calls, such as to 
set or get widget resources using XtSetValues ( ) and Xt:Get:Va-lues ( ). Widgets also 
respond directly to events from the user. Widgets contact the application when certain things 
occur using callbacks or actions. Widgets pass data back and forth using special kinds of 
events. All these types of communication can be thought of as forms of messages. 

Encapsulation 

Objects are intended to be black boxes with documented inputs and outputs. In other words, a 
program that uses an object must not depend on the internal implementation of the object, but 
instead only on the known inputs and outputs. This is called code encapsulation. The advan- 
tages of code encapsulation are that programmers can use the object without needing to 
understand its internal implementation (hiding details), and that the internal implementation 
of the object can be changed at any time because no other code depends on it. This can be 
stated in another way: it minimizes interdependencies. In large software projects, this one 
feature makes OOP worthwhile. 

This encapsulation is very effective in Xt. You should be able to get a long way toward com- 
pleting an application without even needing to know what the code inside a widget looks 
like, let alone the details that implement a particular widget. For that reason, in this book we 
don't show you what is inside a widget until Chapter 6, Inside a Widget. Even when you do 
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know how widgets are implemented, it is a good idea to "'forget" while writing application 
code, so that you are not tempted to depend on implementation details. 

Each widget class has a public include file and a private include file. The application 
includes just the public include file, while the actual widget code includes the private (which 
happens also to include the public). The names of both include files are based on the class 
name of the widget, but the private include file adds the letter P to the end. For example, the 
Label widget's public include file is Label.h, while its private include file is LabelP.h. Appli- 
cation code should include only the public include file, to maintain the desired encapsulation. 
It is tempting for beginning Xt programmers to include the private include file, because it 
allows you to take shortcuts, but you should resist the temptation.? 

2.2 Structure of Applications 

All Athena applications have the same basic structure, as follows: 
1. Include <Xll/lntrinsic.h> and <XI l/StringDefs.h>, the standard header files for Xt. 
2. Include the public header file for each widget class used in the application. (Each widget 
class also has a private header file, which is used in the widget code. Do not include this 
file in your application.) 
3. As of Release 5. Register the locale callback function with XtSetLanguageProc (). 
This function sets up internationalization support. This call is virtually always made with 
three NULL arguments. Always include it as boilerplate: exactly what it does is described 
in Chapter 14. 
4. Initialize the Toolkit with XtAppInitialize ( ) or XtVaAppInitialize (). 
(These two functions do exactly the same thing but have slightly different argument 
styles. The difference is described in Section 2.5.1. Many other Xt functions also have 
two versions with and without "Va" in their names. In the future, unless specifically 
stated otherwise, you can assume that when a sentence mentions one version it also 
applies to the other.) 
5. Create widgets and tell their composite parent widget about them. This requires one call 
to XtVaCreateManagedWidget ( ) for each widget. (Separate XtVaCreate- 
Widget() and XtManageChildren() calls can also be used to speed startup of 
applications with many widgets.) 
6. Register callbacks, actions, and event handlers, if any, with Xt. 
7. Realize the widgets by calling XtRealizeWidget (). This function has to be called 
only once in the entire application, passing it the shell widget returned by XtVaApp- 
Initialize (). This step actually creates the windows for widgets and maps them on 
the screen. This step is separate from creating the widgets themselves, because it allows 

-1- In a language designed for OOP, such as C++, these shortcuts are usually prevented by the compiler or by the lan- 
guage itself. 
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all interdependent widgets to work out their relative size and position before any win- 
dows are created. (For more on geometry management, see Chapter 12, Geometry Man- 
agement.) 

8. Begin the loop processing events by calling XtAppMainLoop (). At this point, Xt 
takes control of your application and operates the widgets. If any widgets are to call 
functions in your application, you must have registered these functions with Xt before 
calling XtAppMainLoop ( ). 

The four steps (3 through 6 above) of initializing the Toolkit, creating widgets, registering 
application functions with Xt, and realizing widgets, comprise the setup phase of the applica- 
tion. Your application should do as much of its work as possible in this phase, before calling 
XtAppMainr,oop ( ), in order to speed up the second phase of the application (which is the 
event loop). This policy improves the response time to user events.% As we will see in 
Chapter 6, Inside a Widget, this policy also applies to the code inside a widget. It is basic to 
X, and indeed to any event-driven system. 

2.3 A Simple X Toolkit Application 

Some application code that uses the X Toolkit will go a long way to illustrate the basic con- 
cepts introduced above. 

Figure 2-10 shows the actual window created by a minimal "'hello, world" Toolkit application 
xhello, and Example 2-1 shows the code for it. xhello simply displays the string "hello" in a 
window. 

i t )i:t,[;]l[,i .... rJ_il 
IHello, Worldf 

Figure 2-10. xhello: appearance on screen 

Most window managers add a decorated border above or surrounding the window; this is not 
part of the application. Likewise, the placement of the widget on the screen depends on the 
window manager. Since no coordinates are specified as resources for the widget, most win- 
dow managers will require the user to place it interactively. Some window managers can be 
configured to place new windows at an arbitrary default location. 

t In X Protocol terms, the setup phase consists of requests to the server that are generally long, and often require im- 
mediate replies, which tends to slow performance. The event loop phase, on the other hand, generally consists of 
short requests and very few "round-trip" requests. For a full description of this concept, see the introductory chapter 
to Volume Zero, X Protocol Reference Manual. 
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2.3.1 The Code 

Example 2-1 shows the code for xhello.c. 

Example 2-1. xhello.c: a minimal "hello, world" application 
/* 
* xhello.c - simple program to put up a banner on the display 
*/ 
/* 
* Include files required for all Toolkit programs 
*/ 
#include <Xll/Intrinsic.h> /* Intrinsics Definitions*/ 
#include <Xll/StringDefs.h> /* Standard Name-String definitions*/ 
/* 
* Public include file for widgets we actually use in this file. 
*/ 
#include <Xll/Xaw/Label.h> /* Athena Label Widget */ 
main (argc, argv) 
int argc; 
char **argv; 
{ 
XtAppContext app_context; 
Widget topLevel, hello; 
topLevel = XtVaAppInitialize( 
&app_context, /* Application context */ 
"XHello", /* Application class */ 
hJLL, 0, /* conmand line option list */ 
&argc, argv, /* conmnd line args */ 
hJLL, /* for missing app-defaults file */ 
NULL) ; /* terminate varargs list */ 
hello = XtVaCreateManagedWidget ( 
"hello", /* arbitrary widget name */ 
labelWidgetClass, /* widget class from Label.h */ 
topLevel, /* parent widget */ 
hJLL) ; /* terminate varargs list */ 

/* 
* 

Create windows for widgets and map them. 
XtRealizeWidget(topLevel); 

/* 
* Loop for events. 
*/ 
XtAppMainLoop (app_context) ; 
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This is fundamentally different from procedural programming, where the application is in 
charge and polls for user input at certain points. 

2.3.2 

Compiling the Application 

You can get the code for xhello.c and all the rest of the examples in this book via uucp, anon- 
ymous ftp, or email, as described in the Preface. It is a good idea to compile and run each 
example as it is presented. 
The example programs come with lmakefiles that should make building them easy if you 
have the intake program (which should already be in /usr/bin/Xll on UNIX-based systems 
that have X installed), and you need the configuration files, in/usr/lib/Xll/config on most 
UNIX-based systems. The source for imake and the configuration files are also in the X distri- 
bution from MIT (see Appendix F, Sources of Additional Information, for how to get this dis- 
tribution). 
An Imakefile is a system-independent makefile that is used by imake to generate a Makefile. 
This is necessary because it is impossible to write a Makefile that will work on all systems. 
You invoke imake using the xmkmf program (also in/usr/bin/Xl I and on the X distribution). 
Complete instructions for compiling the examples using intake are provided in a README 
file in the example source. Note that the examples are designed to work with Motif 1.2, and 
will probably not work with Motif I. 1 or earlier versions. 
To compile any of the examples on a UNIX system without using intake, use the following 
command line: 
cc -0 -o filename filename.c -iXaw -iXmu -iXt -IXll -iXext 
If you want to do debugging, replace -0 with -g in this command line. The order of the 
libraries is important. Xaw relies on Xmu and Xt, Xmu relies on Xt, and both Xaw and Xt 
rely on Xlib (the -IXII link flag specifies Xlib). Xaw also uses the Shape extension which is 
included in the Xext extension library. 

2.3.3 

The App-defaults File 

As mentioned above, the resource mechanism allows widgets to be customized. Widget 
resources can be set from any one of several sources, including a user's resource file, the 
command line, or an application-specific defaults file. 

Each resource of a widget has a default value determined by the widget class that declared 
the resource. However. in many cases, the application wants a different default value, but 
still wants the user to be able to change the value of that resource. 

The Label widget is a case in point. Example 2-I (xhello) sets the default string displayed in 
the Label widget, "hello," by naming the widget hello in the call to XtVaCreate- 
ManagedWidget ( ). It just so happens that the Label widget uses its widget name as the 

Introduction to the X Toolkit 35 



string to be displayed if no other string has been specified in the resource database. However, 
this trick doesn't exist for the other resources of Label or of other widgets. 

The application can provide a default value for resources by hardcoding them in the applica- 
tion source file using the fallback resources argument of XtAppTni ti ali ze (). However, 
changing these settings would require recompiling the source. Xt provides a better way. To 
provide defaults, applications should always create an "app-defaults" resource file, which on 
most UNIX systems is usually stored in the directory /usr/lib/Xll/app-defaults.% For any 
application, the name of this file should be the same as the classname argument to Xt- 
VaAppInitialize (). By convention, this string is the same as the name of the applica- 
tion, with the first letter capitalized. If the application name begins with X, the first two 
letters may be capitalized, but this is not required. For xhello we use XHello. 

Example 2-2 shows the contents of the app-defaults file necessary to make xhello display the 
string "Hello, World!" instead of the default "hello." 

Example 2-2. XHello: the app-defaults file 
*hello. label: Hello, World.' 
The name of the widget instance whose string we are setting is hello, and the Label 
widget's resource that sets the string is label. After the colon is the string we want the 
widget to display. The string should not be quoted. White space after the colon is ignored. 
All resource settings in app-defaults files should start with an asterisk, instead of specifying 
the application name or class (xhello or XHello). This is important as it allows the user to 
easily override this setting, for reasons described in Chapter l0 in the discussion of the ? 
wildcard. 
The app-defaults file has the same format as all other resource database files. In brief, there 
are two types of resources: application resources and widget resources. (You already know 
about widget resources. Application resources are the same except that they apply to the 
application code instead of to individual widgets. Application resources are defined by the 
application writer--how to do this is described in Chapter 3, More Techniques for Using 
Widgets.) 
The syntax for specifying application resources in a resource file is simple: 
application_name .resource_name: value 
Widget resources are more complicated since there may be multiple instances of the same 
widget class in an application. As a result, you must specify the name not only of the widget, 
but a pathname starting with the application name and containing the name of each widget in 
the widget hierarchy leading to the desired widget. For example, in the application xhello, 
the complete resource specification for the resource called label for the Label widget called 
hello would be: 

xhello.hello.label: Hello, World! 

i'On Sun systems under OpenWindows the default location for the app-defaults files is the/usr/openwin/lib/app-de- 
faults directory. On all systems Xt provides a mechanism that allows you to provide a different app-defaults file for 
each language. This will be described in Chapter 10, Resource Management and Type Conversion. 
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Is the X Toolkit Too Complex? 
An editorial aside 

Window systems may be simple to use, but they are very complex to program. The first 
thing that strikes the novice X programmer is how complicated everything is. Learning 
to program the X Window System, even with the help of the X Toolkit, is a far cry from 
learning say, the C programming language, where the very first page of the tutorial 
presents a complete running program. The program itself is trivial, but this, the "hello 
world" program, has become a tacit benchmark of programmability. The assumption 
is "if you can't write 'hello worM' simply, things are badly designed." 
In fact, "hello, world" is a pathological example for X; it is a case where the stylized 
scaffolding outweighs the functional code. You' ve just seen an X Toolkit equivalent to 
"hello world," and it is nearly thirty lines long. But it is node-independent, does 
device-independent graphics, and can be customized by the user to control what font to 
use, and what color to use for the border, background, and text. 
The "hello world" example is indeed a good benchmark of language complexit).,, but it 
is not necessarily a good general benchmark for overall programming complexity. It is 
an especially poor measure for a system that encompasses a generalized distributed 
software environment, network communication, and device-independent graphics. 
Most people write complicated applications, not trivial programs like "hello, world," 
and it is the ease with which a complicated program can be written that is the true test 
of a language. 
For example, consider the difference in the number of lines of code between "hello 
world" and a text editor. Kernighan & Ritchie's C Programming Language, where 
"hello world" was first introduced, doesn't present an editor. However, Kernighan and 
Plaugher's Software Tools, an equally sacred reference from the same era, presents a 
text editor that contains well over one thousand lines. Furthermore, the editor is line- 
oriented, not screen-oriented. By comparison, because of the modular design of the 
Toolkit, and the development of widgets as reusable user-interface components, a pro- 
grammer can construct a simple screen editor using the Text widget in about 170 lines 
of code. This editor is user-configurable, device-independent, and based on a ready- 
made component that can easily be incorporated into any program needing to provide 
text-editing capabilities. 
This is not to invite absurd comparisons of incommensurate programming tools, but to 
emphasize that the complexity of X is the outgrowth of added functionality, not unnec- 
essary convolutions of straightforward algorithms. What really matters is what fea- 
tures are provided, how difficult is it to write the kind of application you want to write 
and what performance can be achieved. 

--Mark Langley 
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and almost ready for release, then it's time to determine which resources need to be hard- 
coded, and then to hardcode them. 

2.4 Connecting Widgets to Application Code 

The Toolkit is designed so that the code that implements the user interface and the code that 
implements application features can be kept separate. This is an advantage, because it allows 
either part to be modified without affecting the other. However, these two pieces of code 
need to be intimately connected, because the user interface must drive the application code. 
This section describes how to make this connection using callbacks. As mentioned earlier, 
the general idea is that the application registers functions to be called later by Xt in response 
to occurrences within certain widgets. 
Callbacks are the method used when taking advantage of features of existing widgets. There 
are other methods, using actions in combination with translations or event handlers, but they 
are used primarily when adding functionality to widgets. The main purpose of actions is to 
modularize the code within a widget that responds to events. The use of actions in the appli- 
cation will be demonstrated in Chapter 4, and in widget code in Chapter 6. 
A callback list is a widget resource. The application can add a callback routine to a widget 
using XtAddCallback ( ) or XtAddCallbacks ( ) only if the widget has declared a call- 
back list as a resource. When a widget has a callback resource, it means that the widget 
writer foresaw that users of the widget would want to have application code called in 
response to a particular user behavior in that widget. 
A widget class may have more than one callback resource. The Scrollbar widget, for 
example, has two, in addition to those defined by its superclass Core. Each callback resource 
represents a very specific occurrence in the widget. This allows you to specify a different 
function to handle each of these different occurrences. One of these resources, XtNj ump- 
Proc, is called when the user indicates that the display should jump to a new position in the 
data. XtNscrollProc indicates that the data should be paged up or down. Each of these 
callbacks indicates a different kind of user behavior, and requires a different kind of move- 
ment of the data in the associated window. The callback function registered with each of 
these callback resources would actually move the data in the various ways. All widgets also 
have the callback XtNdestroyCal lback, which is called when the widget is destroyed. 
Note that a callback function is registered for a specific callback resource and on a specific 
widget instance. Therefore, two widgets can have different functions registered for the same 
callback resource. 

The next section describes how to use callbacks, since they are by far the more often used of 
the two techniques to link the user interface with application code. The use of actions is 
demonstrated in Chapter 4, An Example Application. 
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2.4.1 Callbacks 

To illustrate the use of callbacks from the application, we will write an application that uses 
the Command widget. Some analogue of this widget is present in every widget set. It con- 
tains a string or picture, and executes a command when a pointer button is clicked on it. 

A Command widget calls an application function when you press and release the first pointer 
button (by default) in its window. When you press and hold the pointer button in the Com- 
mand widget's window, the Command widget redraws the window in inverse video. This 
gives the illusion that the button is actually being pressed into the screen. Moving the held 
button out of the window resets the widget without executing the command. 

The xgoodbye program creates a single Command widget. It is very similar to xhello, but 
takes advantage of the callback provided by the Command widget. Clicking on the "Good- 
bye, Cruel World" button exits the program. 

Figure 2-11 shows the window that xgoodbye creates if you have installed the suggested app- 
defaults file (otherwise, it will display "goodbye"). It is suggested that you compile and run 
xgoodbye.c, testing its response to moving the pointer in and out of its window, and clicking 
the various pointer buttons on its window. 
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Figure 2-11. The appearance of xgoodbye when the pointer is in the window 

This example is not as frivolous as it seems. Many applications use code identical to this to 
implement their "Quit" button. 

The code for xgoodbye.c is shown in Example 2-3. 

Example 2-3. xgoodbye.c: complete code 
/. 
* xgoodbye.c - simple program to put up a banner on the display 
* and callback an application function. 
*/ 
#include <stdio.h> 
/* 
* Include files required for all Toolkit programs 
*/ 
#include <Xll/Intrinsic.h> /* Intrinsics Definitions */ 
#include <Xll/StringDefs.h> /* Standard Name-String definitions */ 
/* 
* Public include file for widgets we actually use in this file. 
*/ 
#include <Xll/Xaw/Cranand.h> /* Athena Ccnand Widget */ 
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Example 2-3. xgoodbye.c: complete code (continued) 

/* 
* Quit button callback function 
*/ 
/* ARGSUSED * / 
void Quit(w, client_data, call_data) 
Widget w; 
XtPointer client_data, call_data; 
{ 
fprintf (stderr, "It was nice knowing you. \n" ) ; 
exit(0) ; 
} 

main(argc, argv) 
int argc; 
char **argv; 
{ 
XtAppContext app_context; 
Widget topLevel, goodbye; 
topLevel = XtVaAppInitialize( 
&app_context, /* Application context */ 
"XGoodbye", /* Application class */ 
NULL, 0, /* command line option list */ 
&argc, argv, /* command line args */ 
NULL, /* for missing app-defaults file */ 
NULL); /* terminate varargs list */ 

goodbye 

= XtVaCreateManagedWidget( 
"goodbye", /* arbitrary widget name */ 
commandWidgetClass,/* widget class from Command.h */ 
topLevel, /* parent widget*/ 
NULL); /* terminate varargs list */ 

XtAddCallback(goodbye, XtNcallback, Quit, 0 /* client_data */); 
/* 
* Create windows for widgets and map them. 
*/ 
XtRealizeWidget(topLevel); 
/* 
* Loop for events. 
*/ 
XtAppMainLoop(app_context); 

And here is xgoodbye's app-defaults file: 

Examp 2-4. XGoodbye: e app-deultsfile 
*goodbye.font: *courier-bold*180*iso8859-1 
*goodbye.label: Goodbye, Cruel World! 

The differences between xgoodbye and xhello all apply to adding a callback function. In this 
example we have some application code (the Quit: function) that we register with Xt as a 
callback function for the widget called goodbye using the Xt:AddCa'l ]back ( ) call. 
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2.5 More About Resources 

You now have read about enough techniques to construct an application that uses widgets for 
its user interface and connects the widgets to application code. However, in order to really 
take advantage of any widget class, you have to learn about its resources, so that you can set 
the desired resources in the app-defaults file. 
A class defines its own resources and also inherits the resources of all its superclasses. For 
example, Command supports not only its own resources but also the resources of its super- 
classes, Label and Core. The documentation for a widget class may describe only the 
resources for that class and list the name of the immediate superclass (which you can then 
look up), or it may list all the resources of that class and all superclasses. 

2.5.1 

Setting and Getting Resources from the Application 

Resources are not just for customization of widgets at application startup. The application 
can change resources of widgets that have already been created, before or while the applica- 
tion is displayed. The application can also query the value of most resources. This section 
describes first how to set resources and then how to get them. 

Setting resources is perhaps most often used for resetting strings in Label widgets. This can 
be very useful, but you should be aware that setting a resource from the application wipes out 
the app-defaults or user-specified value for that same resource (if any), unless you first query 
the resource, and then set it based on its earlier value. It is especially important not to hard- 
code strings if you want to be able to change the language used by the application simply by 
changing app-default files. 

There are two parallel sets of functions that set or get resources. The two versions of each 
function have the same name except that one begins with Xr_Va and the other with Xr_ only. 
The arguments of both functions pass in or pass out resource name/value pairs, but they do it 
using a slightly different format of arguments. The Xr_Va style uses an ANSI C varargs list, 
which is a NULL-terminated list of resource name/value pairs. The Xt: version takes an array 
of Arg structures (called an ArgLd.sr.) and an array length. Each Arg structure contains a 
resource name/value pair. We will call these two styles the varargs style and the ArgList 
style. 

The ArgList routines were the only interface until R4, and they can still be used. Using the 
ArgList form of call is slightly more efficient than the varargs form, since internally the 
varargs routines simply massage their arguments into the ArgList forms. However, the Arg- 
List form is more verbose, hard to read, and error-prone, and lacks some of the features sup- 
ported by the varargs form. The loss of efficiency of the varargs form is probably insignifi- 
cant unless you depend on maximum speed in setting or getting resources many times in a 
loop. We use the varargs interface in most of this book, but will also show you how to use 
the ArgList form in the following sections so that you can understand existing applications 
written using them. 
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The following sections demonstrate how to set and get resources of an existing widget using 
the ArgList and varargs interfaces. The same form of arguments are used in many other func- 
tions that set resources, often while creating various types of widgets. Table 2-1 presents the 
parallel lists of Xt functions. The final arguments of all of these (many of which have not yet 
been described) are used in exactly the same manner as in the examples shown in Sections 
2.5.1.1 and 2.5.1.2. 

Table 2-1. Functions that Set Resources: ArgList and varargs Counterparts 

ArgList 

XtSetValues() 
XtGetValues() 
XtCreateWidget() 
XtCreateManagedWidget() 
XtAppCreateShell() 
XtGetSubresources() 
XtGetApplicationResources() 
XtCreatePopupShell() 
XtSetSubvalues() 
XtGetSubvalues() 
XtAppInitialize() 

Varargs 

XtVaSetValues() 
XtVaGetValues() 
XtVaCreateWidget() 
XtVaCreateManagedWidget() 
XtVaAppCreateShell() 
XtVaGetSubresources() 
XtVaGetApplicationResources() 
XtVaCreatePopupShell() 
XtVaSetSubvalues() 
XtVaGetSubvalues() 
XtVaAppInitialize() 

2.5.1.1 Setting Resources with the Varargs Interfaces 

The easiest way to set and get resources is to use the Xt functions XtVaSetValues ( ) and 
XtVaGetValues(). Each of these functions takes a widget argument and a variable 
length list of resource name/value pairs, terminated by NULL. 
All strings should really be read from the resource database or from files, not defined in the 
code, so that the application can be easily used in a foreign language. But for simplicity we 
have shown the strings defined in the code. 

Example 2-5 shows the code needed to change the string of a Label widget--this will work 
any time after the widget has been created, either before or after the widget is realized. 

Example 2-5. Using XtVaSetValues to set a widget resource 
static String new_label = "Hi there." 

XtVaSetValues (w, 
XtNlabel, new_label, 
XtNjustify, XtJusti fyRight, 
NULL); 

/* resource setting */ 
/* resource setting */ 
/* terminate varargs list */ 

Note that a single XtVaSetValues ( ) call can set any number of resources of a single 
widget instance. This example also changes the justification of the string (which by default is 
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centered). (In order for justification to appear, the widget must be wider than the string being 
displayed. This can be arranged with the resource setting *hello.wi dth: 400.) 
The resource names used in the above example are XtNjustify and XtNlabel. The 
include files <Xll/Xaw/Command.h> and <Xll/StringDefs.h> contain these resource name 
symbolic constants. Resource names are actually strings. These strings are stored in sym- 
bolic constants to improve compile-time checking. If you misspell a symbolic constant, the 
compiler will note the error. If you misspell a string, on the other hand, the error will go 
unnoticed by the compiler and go unnoticed at run time as well, but the resource setting will 
do nothing. Therefore, all resource names are specified using constants of the form 
XtNname, where name is the resource name. 
Also note that the value specified for each resource set in the code must be the type expected 
by the widget for that resource, or an error will occur. In this case, the type is String 
(defined as char *), which is what you'd normally use for strings. But for color resources, 
for example, the widgets expect pixel values, not color names. In XtVaSetValues ( ) calls 
(and XtSetValues ( ) calls described in the next section), conversion from strings to the 
appropriate type does not happen automatically as it does for settings in resource files. How- 
ever, you can arrange for it to happen by placing special arguments in the XtVaSet- 
Values ( ) call, as described in Section 3.7.1. (Note that this is a feature of the varargs 
interfaces that is not supported by the ArgList interfaces.) 

NOTE 

Don't set resources of type float using the XtVaSetValues() interface. 
On some systems float is widened to double (as specified in the Kernighan 
& Ritchie C manual). When this widening occurs, half the bytes are read by the 
Intrinsics as a float, and the next 4 as the string name of another resource. 
This can point into invalid memory, and cause a segmentation fault. Use Xt- 
SetArg() and XtSetValues() to avoid the problem. However, since the 
value field of the Arg is a long which may not be the same size as a float, 
use the following approach: 
Arg arg; 
union { 
int int_value; 
float float_value; 
} value; 

value.float_value = 3.2; 
XtSetArg (arg, "name", value.int_value); 
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2.5.1.2 Setting Resources with the ArgList Interfaces 

As mentioned above, the use of the ArgList interfaces is less elegant than the varargs 
interfaces just described, and ArgList interfaces lack the ability to use Xt's value conversion 
mechanism. However, the ArgList interfaces were the only interfaces until R4, and therefore 
are used in most existing applications. Example 2-6 shows how to set resources using Xt- 
SetValues (). 

Example 2-6. Using XtSetValues to set a widget resource 
Arg arg; 
static String new_label = "Hi there." 

XtSetArg(arg, XtNlabel, new_label) ; 
XtSetValues(w, &arg, i); 
The Arg type is defined as a structure containing the name and value pair that defines a 
resource: 
typedef struct ( 
String name; 
XtArgVal value; 
} Arg, *ArgList; 
The definition of XtArgVal differs depending on architecture--its purpose is precisely to 
make code portable between architectures with different byte sizes. Its use in application 
code is demonstrated in Section 3.8.2. All resource values (in all varargs and ArgList calls) 
are limited to the size of XtArgVal, which is the largest of char *, caddr_t, long, 
int *, and proc *. This means that for larger pieces of data, a pointer must be used. For 
example, data of type float or double must be passed as pointers. The documentation for 
a widget class that declares a resource with a large value should document the fact that a 
pointer must be passed rather than the value itself. 
XtSetArg ( ) is a macro that makes it more convenient to set the two members of the Arg 
structure. If desired, you can also set the Arg structure members like any other C structure 
by using the . or -> syntax. 
Note that the first member of Arg is of type String, but should be set to one of the XtN 
resource name constants. 
XtSetValues() is the call that actually changes the widget resource. You pass it the 
widget to be reconfigured, a list of Arg structures, and the length of the list. Example 2-6 
sets only one resource, so the list length is 1. 
XtSetValues () can set any number of resources of a single widget instance. Example 
2-7 shows the code necessary to set two resources. Compare this to Example 2-5 to see how 
much clearer the varargs interfaces are. 

Examp 2-Z Code fragment tosetmultipresources of a widget 
static String new_label = "Hi there." 
Arg args[3]; 
int i; 
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Example 2-9. Code fragment to get a widget resource using XtGetValues 
#define MAXLEN 256 

Widget hello; 
Arg arg; 
char userstring[MAXLEN]; /* memory allocated */ 
String p; /* NOTE - memory for array not allocated */ 

/* Label widget named hello created here. */ 
XtSetArg (arg, XtNlabel, &p) ; 
XtGetValues(hello, &arg, i); 
strcpy (userstring, p) ; 
Note, however, that some resources are not designed to be queried. For example, translation 
tables and callbacks are compiled into an internal representation, so it is pointless to try to 
read them. 

2.5.2 

Core Resources 

The most basic widget class defined by Xt is Core. All widgets are subclasses of Core. 
Therefore, the resources of the Core class are available for all widgets. Table 2-2 shows the 
Core resources. These are defined in <XI l/StringDefs.h>. 

Table 2-2. Core Resources 

Name 

XtNx 
XtNy 
XtNwidth 
XtNheight 
XtNscreen 
XtNcolormap 
XtNdepth 
XtNbackground 
XtNbackgroundPixmap 
XtNborderWidth 
XtNborderColor 
XtNborderPixnap 
XtNtranslations 
XtNaccelerators 
XtNmappedWhenManaged 

Type 

Position 
Position 
Dimension 
Dimension 
Pointer 
Pointer 
int 
Pixel 
Pixnap 
Dimension 
Pixel 
Pixnap 
XtTranslations 
XtTranslations 
Boolean 

Default 

0 
0 
0 
0 
fm Di splay 
from parent 
from parent 
White 
NULL 
1 
Black 
NULL 
NULL 
NULL 
True 
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XtNtranslations is the resource that contains the translation table that maps events into 
actions. As is described exhaustively in Chapter 8, Events, Translations, and Accelerators, 
by setting this resource you can change the events that trigger a widget's actions or the 
actions your application has registered. XtNaccelerators contains an accelerator table. 
(Accelerators are an extended form of translations that allow events in one widget to be 
bound to actions in another.) 
XtNmappedWhenManaged is a resource used by geometry-managing widgets to specify 
whether a widget should be eligible for display (i.e., mapped to the screen) as soon as it is 
placed under parental geometry management, or whether this should not happen until some 
later time. We'll talk more about this concept in Chapter 12, Geometry Management. 
The XtNdestroyCallback resource, as mentioned in Section 2.4.1 above, lets you 
provide an application function to be called when a widget is destroyed. This is infrequently 
used, since the Toolkit normally handles the job of freeing widget data structures and any 
server resources. 
The XtNsensitive resource controls whether a widget responds to user input. This 
allows you to turn on or off user input in a certain widget at will. For example, if you have a 
Command widget whose command is not allowed at certain times, you would set 
XtNsensitive to False during the period the command is not allowed. The Command 
widget changes its own look to indicate that it is invalid. 
The XtNancestorSensitive resource specifies whether the widget's parent (or earlier 
ancestor) is sensitive. Sensitivity is automatically propagated downward, such that if any 
ancestor is insensitive, a widget is insensitive. This resource rarely needs to be set, but is 
sometimes useful to query. 

2.5.3 

Other Inherited Resources 

Besides the resources inherited from Core, a widget inherits resources from each of its 
superclasses. For example, the Command widget used in xgoodbye inherits resources from 
its superclass, the Label widget class, and from Label's superclass, Core. As shown in Table 
2-3, these include, in addition to the label string itself, a font, a foreground color, spacing 
above and below the string, and a value specifying how the string should be placed in the 
widget. (Note that there are many other resources not listed.) 

Table 2-3. Label Resources 

Name 

XtNforeground 
XtNlabel 
XtNjustify 
XtNinternalHeight 
XtNinternalWidth 

Type 

Pixel 
String 
XtJustify 
Dimension 
Dimension 

Default 

XtDefaultForeground 
widgetname 
XtJustifyCenter 
2 (pixels) 
4 (pixels) 
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It is a worthwhile exercise to experiment with the resources available to an application 
through its widgets, even with such a simple example as xgoodbye. For example, consider 
the resource settings for goodbye shown in Example 2-10.% 

Example 2-10. Alternate resource settings for xgoodbye 
! Core resources 
! 
! The follcing two lines don't work, but demonstrate a point 
*farewell.x: i00 
*farewell.y: i00 
., 
! Even though the following specification syntactically applies to 
! all widgets in the application, and all windows have borders, the 
! borderWidth resource value is only used by certain widgets. 
! Cd is not one of them, so this instruction is ignored. 
! 
*borderWidth: i0 
! 
*farewell.width: 200 
*farewell.height : i00 
* farewel i. translations : #override\n\ 
Shi ft<BtnlUp>: quit ( ) \n\ 
<BtnlDown>, <BtnlUp>: confirm ( ) 
! 
! Label resources 
! 
*farewell. foreground: blue 
*farewell. font : helvetical6b 
*farewell. label : Click on me. 

Note that an exclamation point (!) in column zero begins a comment line in a resource file. 
The number sign (#), the standard UNIX comment symbol, should not be used. 
These settings can either be placed in an .Xdefaults file in your home directory, or you can 
save them in any file you like and load them into the server using the xrdb client, as follows: 
xrdb -merge resource_f il e 

(If you want to repeat the experiment with different values, you should be aware that once 
resources are set with xrdb, they remain in effect. Subsequent invocations of xrdb -merge 
will replace settings for the same resources, but won't remove any others that were set 
before. To start with a clean slate, use xrdb -load instead. Note, however, that this will 
replace all of your resource settings, including those for other applications. See Chapter 10, 
Setting Resources, of Volume Three, X Window System User's Guide, Standard Edition, for 
more information on using xrdb. See Chapter l0 of this book for more information on other 
possible sources of resource settings.) 

The window that results when you run xgoodbye with these resource settings is shown in 
Figure 2-12. 

% See Appendix B, Specifying Fonts and Colors, for more information on the font resource specification shown in the 
example. 
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Another surprising fact appears if you set the foreground resource to the same color as the 
background. No text appears in the window, and it does not highlight itself when you move 
the mouse inside. However, if you click a button, you will find that the widget is still 
working. What is happening is that the background and foreground colors are now both the 
same, and therefore there is no contrast with which to see the widget's drawing. The widget 
is not sophisticated enough to check that its two colors are not the same. (Adding this simple 
check would be easy, but it is much more difficult to tell whether two colors that are not the 
same contrast enough.) 

The cautionary point is that there may be unexpected interactions between resources in 
widget code. Like programs in general, widgets tend to do what you say, not what you mean. 
A well-designed widget will minimize ill effects, but given the amount of customization that 
is possible, it may take some time to uncover all the possible pitfalls. Unfortunately, the 
documentation for most existing widgets doesn't always do a good job of explaining how 
resources are used inside the widget. 

2.6 Advice on X Programming 

The X Window System is a very complex collection of software, not to try your patience, but 
to do things that no programming tools have done before. Not only does X provide tools to 
build a nice user interface, but it does so with network transparency, so that programs can run 
on any hardware and operating system and display on any other. 

Probably the best feature of all from the application developer's point of view is the 
portability of the source between hardware and operating systems. It is worth a lot of 
aggravation to be able to write just one version of a piece of software, and have it able to 
compile and run on anything from a PC-compatible to a Cray. 

The price you pay for these features is additional complexity. The key to programming X 
successfully is to keep things as simple as possible by keeping this complexity hidden. 
By choosing to use Xt you have taken a first step to isolate your application from the details 
of the lower levels of X software. In general, use the highest-level tools available. Use Xt 
functions instead of Xlib functions when equivalents are available. 
Also beware of configuring widgets too extensively. Every widget has many resources, and 
the number of possible permutations in even one widget makes it impossible for anyone to 
test them exhaustively. At the same time, programmers tend to abuse this flexibility by 
overly configuring widgets. 

Although Athena will undoubtedly be improved to support even more varied interfaces, this 
will take time, and there will always be features that Athena will not support without 
contortions. If you can compromise a little on the details of how your interface should work, 
you will be better off. With Athena, you can get 90 percent of what you want in a very short 
time. Think twice before spending lots of time trying to get the last 10 percent. If you still 
insist on having that functionality, think carefully about the best way to implement it (and 
consult with someone who knows X intimately, because such a decision may require an 
understanding of Xt, and the lower levels of X). 
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3 

More Techniques for Using Widgets 

This chapter describes how to use some of the more complex widgets found 
in applications, including composite widgets, constraint widgets, and popups. 
It also describes how to define application resources and command-line 
options, and how to hardcode the value of widget resources when you create 
a widget. 

In This Chapter: 
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Figure 3-1. xbox 1: appearance on the screen 

Example 3-1 shows the code that implements xboxl. 

Example 3-1. xboxl.c: complete code 
/* 
* xboxl .c - simple button box 
*/ 

/* 
* So that we can use fprintf: 
*/ 
#include <stdio. h> 

/* 
* Standard Toolkit include files: 
*/ 
#include <Xll/Intrinsic.h> 
#include <Xll/StringDefs.h> 
/* 
* Public include files for widgets used in this file. 
*/ 
#include <Xll/Xaw/Conmvlnd.h> 
#include <Xll/Xaw/Box.h> 

/* 
* quit button callback function 
*/ 
/*ARGSUSED*/ 
void Quit(w, client_data, call_data) 
Widget w; 
XtPointer client_data, call_data; 
{ 
exit (0) ; 
} 

/* 
* "Press me! " button callback function 
*/ 
/*ARGSUSED* / 
void PressMe(w, client_data, call_data) 
Widget w; 
XtPointer client_data, call_data; 
{ 
fprintf (stderr, "Thank you.' \n" ) ; 
} 
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name and class of each widget in your instance hierarchy. To be thorough, also include a 
description of the resources of each class, and specify which resources the user can custom- 
ize. 

The first argument of each XtVaCreateManagedWidget () call is the widget instance 
name. This is the name used to set resources for this widget in the resource databases. Most 
programmers make the widget instance name the same as the variable name of type Widget 
that holds the widget ID. This lexical connection is not mandatory, but it is highly recom- 
mended because it reduces confusion by helping you to remember the connection between 
entries in the app-defaults file and the widget instances in the application. 

3.1.2 

Geometry Management in Practice 

The purpose of geometry managing widgets is two-fold: 
1. They take most of the tedium out of determining the initial positions of widgets. 
2. They recalculate the positions of all the widgets when the user resizes the application, so 
that the application still looks good. 

Build and run xboxl, and then try resizing it to see how the Box widget deals with various 
geometries. This is the default behavior of Box--it can be customized with resources to use 
many different layout rules. Try adding the following resource settings to its app-defaults 
file, run it again, and try out its resizing characteristics. 
*box.orientation: XaOrientVertical 
Two of the resulting geometries are shown in Figure 3-2. 

[ .u .re.. M I ..... .... 

Figure 3-2. Two configurations of xboxl 

What happens if you use resource settings in the app-defaults file to directly set the size or 
position of a widget that is being managed by a geometry managing widget? Depending on 
the specific geometry managing widget, you may not get the desired effect. For example, try- 
ing to set the size of the Command widgets managed by Box may not work. For example, if 
you added the resource setting *pressme.height: 400, it would have no effect on the 
height of the pressme widget. This is because the Box widget needs to ask its parent, the 
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shell widget, to be resized, and this will be denied unless the window manager allows the 
shell to resize itself. The twin window manager will not allow it. However, it is possible to 
set things like geometries in the application code, as will be demonstrated later in this 
chapter. 
Every widget's size and position is ultimately under the control of the window manager.l" A 
Box widget attempts to make itself just big enough to hold its children, using the resources 
provided by the application as a guide, but the window manager can override anything the 
widget or the application does. 
What happens when the user resizes an application is only part of the picture. The applica- 
tion itself may need to resize one of its widgets in order to display more widgets. Or the 
application may tell a widget to display more data and the widget will have to ask its parent 
to be resized. For example, what happens when the application changes the string in one of 
the Command widgets while the application is displayed? The Command widget attempts to 
resize itself to display the current string, by asking its parent for permission. 
Whether this request is granted depends on the position of the widget in the instance hier- 
archy, the resizing policy imposed by each composite widget in the hierarchy, and the win- 
dow manager. This is because each widget, from the Command widget on up, negotiates 
with its parent when the Command widget requests a new size. The Command widget tries 
to change size to accommodate the new string (larger or smaller), and the Box widget must 
approve this change. Since the Box widget is already the same size as the Shell widget, Box 
can't get any larger without asking Shell. The Shell widget is responsible for negotiating 
with the window manager. 
The mwm window manager will allow applications to resize themselves only if the user has 
set the allowShellResize resource to True. (Some other window managers, such as 
twin, never allow it.) Otherwise, the Box widget will reject the resize request unless the orig- 
inal change made the Command widget smaller. If the new size is rejected, the Command 
widget will still display the new string, but it may not show all of the string (if the new string 
is longer than the old one) or there may be extra space left over (if the old string was longer). 
Fortunately, all this negotiation is done by the widgets themselves. The application doesn't 
need to do anything. However, you should be aware that any widget resource change that 
results in a widget size change may not work unless there is enough room in the application 
for the change to be granted without resizing the top-level window. 
The Box widget is the basic geometry managing widget. It is widely used for managing 
groups of small widgets in many settings. However, it treats all its children the same, and 
therefore isn't appropriate for widgets of radically different geometries. Such situations 
make Box's decisions about where to place the widgets inappropriate. Figure 3-3 shows the 
results upon resizing of a Box widget that is attempting to manage two Scrollbar widgets and 
a BitmapEdit widget.$ 

"t" BulletinBoard creates an exception to this rule. Since BulletinBoard never resizes its children, the window manager 
controls which of these children are visible, but does not resize them. 
:The BitmapEdit widget is not part of the Athena widget set. It is used to build an application in Chapter 4, An Ex- 
ample Application, and written from scratch in Chapter 6, Inside a Widget, and Chapter 7, Basic Widget Methods. 
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Figure 3-3. Incorrect results upon resize of Scrollbar widgets inside a Box widget 

As you can see, one of the scrollbars is in the wrong place. It might be possible to use the 
Box resources to make this application look better, but it would be difficult to keep it good 
looking after resizing. 

Because no single geometry managing widget can satisfy all needs, there are several different 
types of composite widgets in most widget sets, each with different rules about how it places 
children. Many widget sets, including Athena, have a widget specifically designed to place 
scrollbars next to a main window. In Athena, this widget is called Viewport. 

Of course, applications are not limited to using only one composite widget. It is quite com- 
mon for the application's main window to be a large composite widget which contains sev- 
eral smaller composite widgets, each of which in turn contains certain groups of related 
widgets. You'll need to design the layout of widgets in your application, decide where in the 
instance hierarchy to place composite widgets, and experiment to find out which composite 
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The resources XtNhorizDistance and XtNfromHoriz specify the widget position 
in terms of a specified number of pixeis horizontally away from another widget in the 
form. As an example, XtNhorizDistance could equal 10 and XtNfromHoriz 
could be the widget ID of another widget in the Form. (When specified in a resource file, 
XtNfromHoriz is set using the instance name of another widget in the form.) The new 
widget will always be placed 10 pixels to the right of the widget defined in XtNfrom- 
Horiz, regardless of the size of the Form. If XtNfromHoriz equals NLrLL, then Xt- 
NhorizDistance is measured from the left edge of the Form. 

Similarly, the resources XtNvertDistance and XtNfromVert specify the widget 
position in terms of a specified number of pixels vertically away from another widget in 
the Form. If XtNfromVert equals Nt.rLL, then XtNvertDistance is measured from 
the top of the Form. 

When set in the application, the values for XtNfromHoriz and XtNFromVert must 
be widget IDs. But in the resource database, widget names are used instead, since the 
actual widget ID changes each time the application is run. This is an example of the 
automatic type conversion built into the resource manager. Resource conversion is 
described in Chapter 9, More Input Techniques. 

The XtNtop, XtNbottom, XtNleft, and XtNright resources tell the Form where to 
position the child when the Form is resized. The values of these resources are specified 
by the enum XtEdgepe, which is defined in <Xll/Form.h>. 

The values XtChainTop, XtChainBottom, XtChainLeft, and XtChainRight 
specify that a constant distance is to be maintained from an edge of the child to the top, 
bottom, left, and right edges, respectively, of the Form. 

The value XtRubber specifies that a proportional distance from the edge of the child to 
the left or top edge of the Form is to be maintained when the Form is resized. The pro- 
portion is determined from the initial position of the child and the initial size of the Form. 
Form provides a StringToEdgepe conversion to allow the resize constraints to be 
easily specified in a resource file. 

The default width of the Form is the minimum width needed to enclose the children after 
computing their initial layout, with a margin of XtNdefaultDistance at the right and 
bottom edges. If the Form is assigned a width and height that are too small for the layout, the 
children will be clipped by the right and bottom edges of the Form. Example 3-3 shows the 
resource settings in a resource file. 

Example 3-3. XBox2: app-defaults file 
*pressme*label: Press Me 
*quit*label : Quit 
*Conr0and *background: green 
*pressme* frcHoriz : quit 
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is actually just a special case of the Form widget. It provides a convenient way to create a 
"preconfigured form" useful for dialog boxes. 
The typical Dialog widget contains three areas. The first line contains a Label widget provid- 
ing a description of the function of the Dialog widget, for example, the string "Filename:". 
The second line contains a Text widget into which the user types input. The third line can 
contain one or more Command widgets that let the user confirm or cancel the Dialog input. 
(Other types of dialogs may just provide buttons to choose from.) The class variable for the 
Dialog widget is dialogWidgetClass. 
Figure 3-6 shows the appearance of xbox3 when the Dialog widget is popped up. 

Figure 3-6. xbox3: popping up a Dialog widget 

Note that without proper resource settings in the application-defaults file, the text entry 
widget will not appear, and the buttons will have different text in them. Example 3-5 shows 
the required application-defaults file. 

Example 3-5. xbox3: application-defaults file 
*value: 
*pressme*label : Press Me 
*quit*label : Quit 
*dialog*label: Enter Text Belcx: 
*dialog*Ccranand*label : Dialog Done 
The *value: resource setting tells the Dialog widget to provide a text entry widget but to 
give it no initial text. 
Expanding xbox to create xbox3 requires five steps: 
1. Creating the pop-up shell widget. 
2. Creating the Dialog widget. 
3. Creating a Command widget as a child of the Dialog widget. (This Command widget is 
used to pop down the dialog box.) 
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4. Changing the callback function invoked by the "Press Me" button so that it pops up the 
widget. 
5. Writing the callback that pops down the widget. 

Example 3-6 shows the code added to xboxl to develop xbox3. 

Example 3-6. Creating a pop-up dialog box 

#include <Xll/Shell .h> 
/* 
* Public include files for widgets used in this file. 
*/ 
#include <Xl i/Xaw/Cd, h> 
#include <Xll/Xaw/Box. h> 
#include <Xll/Xaw/Dialog. h> 
/* 
* Both dialog and pshell are needed in the dialogDone callback, 
* and both can't be passed in without creating a structure. 
* So we chose to pass dialog in, and make pshell global. 
* pressme and quit are needed in both callbacks, so they are 
* declared global as well. 
*/ 
Widget pshell, pressme, quit; 
/* 
* dialog button 
*/ 
void PopupDialog(w, client_data, call_data) 
Widget w; 
XtPointer client_data; /* cast to topLevel */ 
XtPointer call_data; 
{ 
Widget topLevel = (Widget) client_data; 
Position x, y; 
Dimension width, height; 
Arg arg[2 ] ; 
int i; 
/* 
* get the coordinates of the middle of topLevel widget. 
*/ 
XtVaGetValues (topLevel, 
XtNwidth, &width, 
XtNheight, &height, 
NULL) ; 

/* 
* translate coordinates in application top-level window 
* into coordinates from root window origin. 
*/ 
XtTranslateCoords (topLevel, /* Widget */ 
(Position) width/2, /* x */ 
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Example 3-6. Creating a pop-up dialog box (continued) 

(Position) height/2, 
&x, &y); 

/* y */ 
/* coords on root window */ 

/* move popup shell to this position (it's not visible yet) */ 
XtVaSetValues (pshell, 
XtNx, x, 
NULL) ; 

/* 
* Indicate to user that no other application functions are 
* valid while dialog is popped up... 
*/ 
XtSetSensitive (pressme, FALSE) ; 

XtPopup(pshell, XtGrahNonexclusive); 

} 
/* 
* dialog donebutton 
*/ 
void DialogDone(w, client_data, call_data) 
Widget w; 
XtPointer client_data; /* cast to dialog */ 
XtPointer call_data; 
{ 
Widget dialog = (Widget) client_data; 
String string; 
XtPopdown(pshell); 
XtSetSensitive(pressme, TRUE); 
string = XawDialogGetValueString(dialog); 
printf('User typed: %s\n', string); 
} 
/* 
* quit button callback function 
*/ 
void Quit(w, client_data, call_data) 
Widget w; 
XtPointer client_data, call_data; 
{ 
exit(0) ; 
} 
main (argc, argv) 
int argc; 
char **argv; 
{ 
XtAppContext app_context; 
Widget box, topLevel, dialog, dialogDone; 
/* XtAppInitialize, create box, quit, etc. */ 
pressme = XtVaCreateManagedWidget( 
"pressme', /* widget name 
ccmnandWidgetClass, /* widget class */ 
box, /* parent widget*/ 

*/ 
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widget child is added to tell the user the purpose of the box and, with certain resource values, 
an Athena Text widget child is added for text entry. 
Ideally, the Text widget should provide a callback (which could be used to provide the data 
the user entered and pop down the dialog box) when the user types the Return key. Many 
applications add this missing feature by overriding the translation for the Return key in the 
Text widget, or by displaying a Command button to provide the callback. 
The Label widget and Text widget are automatically created as part of the Dialog widget. 
You have to explicitly create the Command widget as a child of the Dialog widget. The Dia- 
log widget does, however, automatically set the constraint resources that Form uses to place 
and size the Command widget. The callback function called by this Command widget is 
called DialogDone. 
The pressme Command widget's callback function is called PopupDialog. Most of its 
code places the pop-up widget, because popups appear at the top left corner of the screen by 
default. This example centers the corner of the pop up in the top-level widget of the applica- 
tion. Since pop up coordinates are relative to the corner of the root window, centering is a 
three-step process: 
1. Get the width and height of top-level window with XtGetValues (). 
2. Translate the center point into root window coordinates with XtTranslateCoords ( ). 
3. Move the pop-up shell by setting XtNx () and XtNy resources with XtVaSet- 
Values (). 

When you pop up a widget from an action instead of a callback, you can use the content of 
the event to place the pop up and avoid the last two steps. 

Pop-up windows appear at the corner of the screen by default because their windows are chil- 
dren of the root window, not children of the top-level window of the application. This allows 
the pop up to extend beyond the border of the application, as was shown in Figure 3-6. 
Pop-up windows are the only difference between the widget hierarchy created by an applica- 
tion and its X window hierarchy. Figure 3-7 shows the two hierarchies for xbox3. 

The PopupDialog callback function sets the Command widgets in the application to insen- 
sitive mode with XtSetSensitive** just before it pops up the dialog box. This is done to 
indicate to the user which Command invoked the current pop up (and that it is futile to press 
that particular Command again now). When the data is furnished, the application must turn 
sensitivity back on again. 

The DialogDone callback function pops down the pop-up shell, sets the application's 
Command widget back to sensitive mode, gets the value the user typed, and prints it. 

tThis could also be done by setting the widgets' XtNsensitive resource with XtSetValues (). Calling Xt- 
SetSensitive ( ) is slightly faster. 
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3.4.1 Passing Data to Callback Functions 

3.4.1.1 

A callback function is called with three arguments: widget, client_data, and 
call_data. 
The widget argument is necessary if you have registered the same callback function for two 
widgets, and you need to know which widget called the function. It also may be used in rou- 
tine ways, such as for the argument of macros. The application determines the use of 
client_data, whereas the widget determines the use of call_data. 

The client_data Argument 

You may pass a single piece of data as the client_data argument, or pass a pointer to a 
structure containing several pieces of data. You may ask, "Why bother with passing data to a 
callback when I can just declare a global variable?" For one thing, it is a general principle of 
good C coding to use a global variable only where the variable is needed in several functions 
and the arguments would otherwise prove unwieldy. Secondly, using the client_data 
argument makes clear the purpose of your variable, whereas it is difficult to trace where a 
global variable is set or referenced. However, if you find it necessary to change the cli- 
ent_data argument in a number of functions in the application, you will need a global 
variable anyway, and there is nothing that says you must use client_data (but be sure to 
document what you are doing!). 
Example 3-7 demonstrates how to pass a single piece of data into a callback function. 

Example 3-7. Passing a single value to a callback function 
/ *ARGSUSED * / 
void PressMe (w, client_data, call_data) 
Widget w; 
XtPointer client_data, call_data; 
{ 
fprintf (stderr, "%s\n", client_data) ; 
} 

main (argc, argv) 
int argc; 
char **argv; 
{ 
Widget pressme; 

/* XtAppInitialize, create pressme widget */ 

/* last argument is client_data */ 
XtAddCallback (pressme, XtNcallback, PressMe, "Thanks" ) ; 
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Example 3-8 demonstrates passing a pointer to a structure into a callback function. Xt- 
Pointer is a generic pointer type with an implementation-dependent definition. It is used 
just like the standard C-type caddr_t. 

Example 3-8. Passing a pointer to a structure to a callback function 
typedef struct { 
String name; 
String street; 
String city; 
} app_stuf f; 

/*ARGSUSED* / 
void PressMe(w, client_data, call_data) 
Widget w; 
XtPointer client_data; /* to be cast to app_stuff */ 
XtPointer call_data; 
{ 
/* cast required in ANSI C */ 
app_stuff *address = (app_stuff) client_data; 

fprintf (stderr, "%s\n%s\n%s\n", address->name, address->street, 
address->city) ; 

main(argc, argv) 
int argc; 
char **argv; 
{ 
XtAppContext app_context; 
Widget box, quit, pressme, topLevel; 

static app_stuff stuff = { 
"John Doe", 
"1776 Constitution Way", 
"Philadelphia, PA 01029" 
}; 

/* XtVaAppInitialize, create pressmewidget */ 

XtAddCallback(pressme, XtNcallback, PressMe, &stuff); 

} 
Note that two coding conventions are required by ANSI C and should be followed, even 
though many compilers will not complain if they are not used. The first convention is that all 
three arguments of the callback must be declared, even if the trailing ones are not used. 
Many compilers will work fine if unused trailing arguments are omitted from the definition of 
the callback fur'.ction. The second is that many compilers will automatically cast Xt- 
Pointer to the type you want if you declare the callback function arguments using that 
type. The cast on the first line of the PressMe callback is required by ANSI C. Example 
3-9 shows a definition of the above callback function that works on many compilers but is not 
ANSI C conformant. Compare Example 3-9 with Example 3-8. 
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Example 3-9. ANSI non-conformant callback function definition 
I*ARGSUSED* I 
void PressMe(w, address /* call_data cmitted */) 
Widget w; 
app_stuff *address; /* ANSI non-conformant cast */ 
/* third arg cmitted - ANSI non-conformant */ 
{ 
fprintf (stderr, "%s\n%s\n%s\n', address->name, address->street, 
address->city) ; 
} 

3.4.1.2 

The call_data Argument 

The call_data argument is passed in to the callback function from the widget itself. This 
argument's value is described in the documentation for the widget class unless it is not used. 
In the Athena widgets, the call_data argument is used in the List, Scrollbar, StripChart, 
and Toggle widgets. In the List widget (a widget that displays a list of strings and allows one 
to be selected), this argument is a pointer to a structure containing the selected string and its 
index. In the Motif widgets the call_data argument is extensively used to pass the event 
structure to the callback function. 

3.4.2 

Callback Lists 

You may register any number of callback functions for a single widget callback resource. In 
other words, when a callback is triggered by a user event, all the functions in the current call- 
back list for that callback for that widget instance will be called, one at a time. Multiple call- 
back functions are not needed in many applications, but can be useful if applied carefully. 

There is no guarantee that the functions on a callback list will be called in the specified order. 
Therefore, each callback function must be independent of all other callback functions on the 
list. This dramatically reduces the usefulness of multiple callback functions. 

Remember that most widgets also have more than one callback list, each triggered by a dif- 
ferent occurrence. What we are talking about here is that you can register a series of func- 
tions to be called in response to one occurrence. 

Let's take an example of how a callback list might be used. Perhaps you have the functions 
A, B, and C, and you need to be able to call them separately in response to events in three dif- 
ferent Command widgets, or to call all of them in response to events in a fourth Command 
widget. How should we structure the callback for the fourth Command widget? The first 
approach is to have a callback list including the functions A, B, and C. This is preferred if A, 
B, and C can be called in any order, since you can pass a different piece of data into each rou- 
tine. The other approach is to register a single callback, function D, that calls A, B, and C. In 
this case you are assured that A, B, and C will be called in the desired order. 

You can also call the same function more than once in a callback list. 
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NOTE 

Never use XtRemoveA11Cal lbacks (). Widget sets such as Motif add their 
own callback functions to many of the widgets, and depend on these functions to 
operate properly. 

One way to add more than one callback function is to call XtAddCal lback ( ) more than 
once. Another way is to call XtAddCallbacks (), which takes an XtCallbackRec 
array as an argument. This array is usually initialized at compile time, as shown in Example 
3-10. The final NULL, NULL entry terminates the list. (This particular list registers the func- 
tions do._A and do_B, and passes them both 0 as client_data.) 

Example 3-10. Initializing a callback list 
XtCallbackRec quit_callback_list [ ] ={ 
{do_A, 0}, 
{do_B, 0}, 
{ (XtCallbackProc) NULL, (XtPointer) NULL} 
}; 

This form of XtCal ibackRec list can also be used to replace a callback list with XtSet- 
Values ( ) (but not to get a callback list, because Xt compiles the list into an internal form). 
An XtCallbackRec list can also be used to register one or more callbacks when creating a 
widget. 

3.5 Application Resources 

You already know that widgets declare resources that can be configured through the resource 
mechanism. In addition, the application itself may have variables that it wants the user to be 
able to configure from the resource databases, even though these variables have nothing to do 
with widgets. These are called application resources. 
Application resources are just like widget resources except that they apply to application 
code, not to the widgets it creates. 
There are three steps for adding application resources. You must: 
1. Create an application data structure containing the variables to be set via the resource 
mechanism. 
2. Create a resource table defining the type and default value for each variable. 
3. Call XtGetApplicationResources () with pointers to the application data struc- 
ture and resource table as arguments. When this function returns, the application data 
structure will contain the current settings from the resource databases. 

To demonstrate how to get application resources, we will jump ahead and describe a portion 
of the code for the xbitmap4 bitmap editor example described in Chapter 4, An Example 
Application. Because this application draws into a widget using Xlib, it needs two colors 
with which to draw. The bitmap editor also allows the user to specify the dimensions of the 
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bitmap in cells, and the size of each cell in pixels. And, for general utility, it includes a 
debug flag that can be set in a resource file to invoke or ignore debugging code without 
recompiling. 

3.5.1 

The Application Data Structure 

The structure type that contains all the application variables to be set through resources is 
commonly called AppData. Once this structure type is declared, memory can be allocated 
for a structure called app_data. Example 3-11 shows the code that defines the structure 
type and then allocates memory for the actual structure. 

Example 3-11. xbitmap: getting application resources 
typedef struct { 
Pixel copy_fg; 
Pixel copy_bg; 
int pixmap_width_in_cells; 
int pinap_height_irLce 11 s; 
int cell_size_in_pixels; 
Boolean debug; 
} AppData; 
AppData app_clata; 
As usual in C, the members of the app_data structure will be referenced throughout the 
application code using the dot format. For example, the value of the debug field of 
app_data will be referenced with app_data, debug. 

3.5.2 

The Resource List 

The resource list looks complicated, but it is easy to understand and even easier to write 
because it conforms to a consistent pattern. Each field in the application data structure has an 
entry in the resource list. Each resource entry in turn has seven fields, which describe the 
name of the resource, its type and default value, and various other information. 

The resource list controls Xt's value conversion facilities. Since user resources are always 
strings, and application data structure fields can be any type, a conversion may have to take 
place. Xt has built-in converters to convert from string to most common types needed by 
applications. These types are called representation types by Xt, and they are indicated by 
constants starting with XtR in standard Xt. The representation type of a string (char *) is 
XtRString. You control the conversion simply by specifying a resource as a certain repre- 
sentation type in the resource list. 
It is possible to represent the same value in several different representation types. For 
example, a color may be represented as an ASCII color name such as "blue," as a structure 
containing Red, Green, and Blue values, or as a pixel value (an index into a colormap). Also 
note that a representation type is different from a C-Language type. It is also possible for 
two different representations of something to both use the same C-Language type. For 
example, two hypothetical representation types might be XtRInch and XtRMeter. Both 
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represent distances and both would probably be integers or floating point numbers, but each 
would have a different value for the same distance. 
See Chapter 10, Resource Management and Type Conversion, for a description of the stan- 
dard representation types, as well as information on how to write your own converter routine. 
Example 3-12 shows the resource list for xbitmap4, followed by a description of each of the 
fields in each entry. 

Example 3-12. The resource list for xbitmap4 
/* 
* The following could be placed in a "xbitmap.h" file. 
*/ 
#define XtNdebug "debug" 
#define XtCDebug "Debug" 
#define XtNpimapWidthInCells "pixmapWidthInCells" 
#define XtCPixmapWidthInCells "pixmapWidthInCells" 
#define XtNpixmapHeightInCells "pixmapHeightInCells" 
#define XtCPixmapHeightInCel is "PixmapHeightInCel is" 
#define XtNcellSizeInPixels "cellSizeInPixels" 
#define XtCCellSizeInPixels "CellSizeInPixels" 
static XtResource resources [ ] = { 
{ 
XtNforeground, 
XtCForeground, 
XtRPixel, 
sizeof (Pixel), 
XtOffsetOf (AppData, copy_fg), 
XtRSt ring, 
XtDefaultForeground 

XtNbackground, 
XtCBackground, 
XtRPixel, 
sizeof (Pixel), 
XtOffsetOf (AppData, copy_bg), 
XtRSt ring, 
XtDe faultBackground 

XtNpixmapWidthInCel i s, 
XtCPixmapWidthInCel i s, 
XtRInt, 
sizeof (int), 
XtOffsetOf (AppData, pixmap_width_in_cells), 
XtRInnediate, 
(XtPointer) 32, 

XtNpixmapHeightInCells, 
XtCPixmapHeightInCells, 
XtRInt, 
sizeof(int), 
XtOffsetOf(AppData, pixmap_height in cells), 
XtRInnediate, 
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3.5.3 Getting the Resources 

Once the application data structure and resource list are set up, you pass pointers to them to 
XtGetApplicationResources (), just after calling XtApplnitialize (). Xt- 
GetApplicationResources ( ) will search the databases for any matching resource set- 
tings and set the fields in the application data structure. 

The last requirement is that you check the values specified by the user to make sure they are 
acceptable. Example 3-13 shows these two steps from xbitmap4. 

Example 3-13. Calling XtGetApplicationResources and checking values 

AppData app_data; 

main (argc, argv) 
int argc; 
char *argv[ ] ; 
{ 
XtAppContext app_cont ext; 
Widget toplevel, vpane, buttonbox, quit, output; 

/* call XtAppInitialize here */ 

XtVaGetApplicationResources(toplevel, 
&app_data, 
resources, 
XtNumber(resources), 
/* varargs list here for making 
* application resources 
* non-user-configurable */ 
NULL); /* terminate varargs list */ 

/* 
* We must check the application resource values here. 
* Otherwise, user could supply out of range values. 
* Conversion routines do this autctnatically, so 
* colors are already checked. 
*/ 
if ((app_data.pixmap_width_irL_cells >MAXBITMAPWIDTH) II 
(app_data.pixmap_width_in_cells < MINBITMAPIDTH) I 
(app_data.pixmap_height_in_cells >MAXBITMAPHEIGHT) II 
(app_data.pixmap_height_in_cells < MINBITMAPHEIGHT)) { 
fprintf(stderr, "xbitap: error in resource settings:', 
"bitapdimensionmust be between %dand %d cells\n', 
MINBITMAPIDTH, MAXBITMAPHEIGHT); 
exit(l); 

if ((app_data.cell_size_in_pixels < MINCELLSIZE) II 
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Example 3-13. Calling XtGetApplicationResources and checking values (continued) 

(app_data.cell_size_in_pixels > MAXCELLSIZE) ) { 
fprintf(stderr, "xbitmap: error in resource settings:", 
"cell size must be between %d and %d pixels\n", 
MINCELLSIZE, MAXCELLSIZE) ; 
exit (i) ; 

} 
Because Xt automatically converts the user's color specifications (such as "blue") into the 
form required by X, it warns the user when an unknown color is specified.% Therefore, your 
code doesn't need to check this kind of validity for values that Xt or Athena converts. How- 
ever, you may need to check for other kinds of validity of the same values. For example, you 
may wish to check that two colors are not the same by comparing values after conversion. In 
this case, only the bitmap dimensions and cell size are checked, since they are critical to the 
application's operation. 

3.6 Command-line Options 

You already know that Xt automatically customizes widgets according to the resource data- 
base, but this is not the whole story. Users often expect command-line arguments for the 
most important aspects of an application. By default, XtAppTnitialize ( ) understands 
only a minimal set of command-line arguments; more need to be added so that application 
resources and certain widget resources can be set from the command line. 

There is no point, however, in trying to make every widget resource settable from the com- 
mand line, because that's the purpose of the resource database. You should concentrate on 
the resources that the user is most likely to want to have different between two simultaneous 
instances of the application (since it is difficult to arrange this with the resource database). 

Before describing how to define your own command-line arguments, we need to describe 
what command-line arguments XtAppTnit ial i z e ( ) already handles. 

'That is, if the resource in a database file is specified properly, but the value is not, XI will warn the user. However, if 
the resource is not specified properly, Xt has no way of knowing that the resource was intended to specify a color, 
and therefore, no message will be issued. For example, "'*background: grein" (sic) will elicit a warning message be- 
cause grein (sic) is an unknown color, but "*backgruond: green" (sic) will not, because the resource identifier is un- 
known. Unknown resource identifiers are simply ignored, because they could apply to some other widget or even 
some other application. 
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XtAppInitialize() doesn't recognize will be left in argv and argc. This is your 
chance to catch this error and tell the user/f The Syntax function shown in Example 3-14 
demonstrates code that informs the user of the proper syntax and the option that was not 
understood. (In response to incorrect command-line options, UNIX programs traditionally 
print only the correct calling sequence. However, you can be even nicer to the user by print- 
ing the option or options that were in error, by passing argv and argc into your Syntax 
function, as is done in Example 3-14. 

Experienced UNIX programmers will note that Xt applications can (but usually don't) use the 
single-letter command-line arguments mandated by POSIX and the System V Interface Defi- 
nition. As mentioned earlier, Xt automatically matches any unique abbreviation for any com- 
mand-line option. For example, by default the -display option can be specified as -d, but 
only if you haven't included any other option in the options table that also begins with d. 
You can define the meaning of single-letter options simply by including them verbatim in the 
options table. In other words, if you specify that -d turns on a debugging resource, Xt will no 
longer try to match any other, longer option that also begins with d. 

Note that the argc and argv arguments of XtAppInitialize () are in the same order 
as in the call to main. This is the opposite order of arrays and array lengths throughout other 
Motif, Xt and Xlib routine calls. Also note that the address of argc, not argc itself, is pas- 
sed to XtAppInitialize ( ). This is so that XtAppInitialize ( ) can decrement the 
count to reflect recognized options. Watch out for these snags. 

3.7 Preventing User Customization of Widget Resources 

Although user customization is good to a certain degree, some resources need to be hard- 
coded to make sure that an application will run properly regardless of user configuration. 
This is particularly true of widget geometry resources and constraints. For example, it is easy 
to make a mistake with Form widget constraints such that some important widget is hidden 
behind others. 
You prevent user customization of particular resources by setting them in the calls to Xt- 
VaCreateManagedWidget ( ) or XtCreateManagedWidget ( ), using a varargs list 
or an argument list as was shown in XtVaSetValues ( ) and XtSetValues ( ) calls in 
Section 7.4. This section will review those techniques and show a few more tricks. 
When resources are set in the calls to create widgets, the application can still modify these 
resources any time later using XtVaSetValues ( ) or XtSetValues (). Therefore, this 
is hardcoding only from the user's perspective. Also note that Xt will not tell the user that 
you have hardcoded certain resources--your application documentation should do this. 
The time to hardcode widget resources is when development of an application is almost fin- 
ished, because until then the resource settings are still in flux and it is quicker to edit the app- 
defaults file than it is to recompile the application. 

# You can, of course, intentionally treat the arguments remaining after XtAppInitiali z e ( ) as filenames or other 
pieces of data. 
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The varargs interfaces will also accept an arglist as one item in the list, using the symbol Xt- 
VaNestedList as the resource name. XtVaNestedList allows you to create one argu- 
ment list and pass it to a series of widget creation routines, instead of listing all the same 
resource settings in each widget creation routine. For more details on this, see 
Chapter 10, Resource Management and Type Conversion. 
There is some extra overhead involved in using the varargs interfaces because they massage 
the arguments into an argument list and call XtCreateWidget ( ), XtCreateManaged- 
Widget (), XtSetValues (), or XtGetValues (). However, the added convenience 
seems worth it. Furthermore, the XtVaTypedArg feature is not supported in the ArgList 
style of call (described in the next section). 
Unless you use the XtVaTypedArg feature, no diagnostic is printed when you specify a 
resource value incorrectly in the argument list. Therefore, make sure you specify the 
resource values correctly, and recognize this as a possible place to begin looking for bugs. 
(This is another reason to hardcode resources only when the application is almost ready for 
release. If you do it all at once in a methodical fashion, you are less likely to make mistakes 
than if you are always adding, subtracting, and changing values in the argument lists.) 

NOTE 

If you use the varargs style of arguments, but forget to type the Va in the func- 
tion name, you can get various types of errors. If you specify resources in the 
call, you will get a core dump at run time, but you can detect the problem with 
lint, which will note the function as having a variable number of arguments. If 
you don't specify resources in the call, the application will run but you will get 
the message: 

Warning: argument count > 0 on NULL argument list 

3.7.2 

Using the Argument List Interfaces 

Widget resources can also be hardcoded by creating an argument list containing the 
resources to be set and their values, and passing it to XtCreatebianagedWidget (). This 
method of setting resources is less convenient that the varargs technique just described, but it 
was the only way until R4, and therefore many existing applications use it. 
An argument list is just an array of Arg structures, of the same type as you set up to call Xt- 
SetValues ( ) or XtGetValues (). Once set, this array is used as an argument to Xt- 
CreateManagedWidget (). Each Arg structure contains a resource/value pair. Attri- 
butes specified here override the same ones specified from the command line or from 
resource databases. 
Example 3-16 shows an argument list that hardcodes the sensitivity of a Command widget 
and its callback list. Sensitivity is a good thing to hardcode for Command widgets, because 
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if accidentally set by the user it could disable an application.t" The callback list cannot be 
specified by the user anyway; setting it here is just an alternative to calling XtAdd- 
Cal iback (). 

The XtArgVal type used in the callback list aids in porting Toolkit programs to different 
architectures. It allows the system manufacturer to select the type in the typedef for Xt- 
ArgVal, so that the application program need not worry about it. The value field of the 
Arg structure may be a number or a pointer. 

Example 3-16. An argument list 
Arg quit_args[ ] = { 
XtNsensitive, (XtArgVal) True, 
XtNcallback, (XtArgVal) quit_callback_list, 
}; 
An argument list can be used as an argument in the call to create a widget, as shown in 
Example 3-17. 

Example 3-17. Using an argument list in widget creation 
/* define quit_args */ 

main(argc, argv) 
int argc; 
char *argv[]; 
{ 
Widget quit, box; 

/* create box */ 

quit = XtCreateManagedWidget( 
"quit', 
ccmandWidgetClass, 
box, 
quit_args, 
XtNumber(quit_args) 
); 

/* widget name */ 
/* widget class */ 
/* parent widget */ 
/* argumant list */ 
/* arglist size */ 

Note the use of the XtNumber ( ) macro to calculate how many arguments there are in the 
statically initialized argument list. This macro eliminates the need to keep track of the num- 
ber of resources you have set. 

% Sensitivity is a basic resource of all widgets. When set to True, the default, a widget accepts input and operates 
normally. When False, a widget displays itself in gray (or otherwise indicates insensitivity) and does not act on 
user input. The purpose of sensitivity is to allow the application to disable certain commands when they are not val- 
id. If sensitivity were left configurable, the user could turn it off on some widgets and effectively cripple an applica- 
tion. It is hard to imagine the user doing this by accident, but it is not worth taking a gamble. 
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3.7.2.1 

Note also that the value field in the argument list must be in the correct representation type 
for that resource, which is often not a string. You may need to call XtConvertAnd- 
Store ( ) to arrive at the right representation of the data to be placed in the argument list. 
For details on calling XtConvertAndStore(), see Chapter 10, Resource Management 
and Type Conversion. An easier way to do this is to use the XtVaTypedArg feature sup- 
ported by the varargs interfaces. 
As mentioned earlier, unless you invoke a converter, no diagnostic is printed when you spec- 
ify a resource value incorrectly in the argument list. Therefore, make sure you specify these 
correctly. 

Another Way to Set Arguments 

Instead of creating the argument list as a static array, you can allocate storage at run time and 
use the XtSetArg ( ) macro to set values into the storage. This is the coding style favored 
in Motif 1.0 applications. 
XtSetArg() sets a single argument to a resource identifying a constant and a value. 
Example 3-18 shows the code that would create an argument list with the same contents as 
the one created in Example 3-16 above. Some people prefer this technique because it places 
the argument list setting closer to the XtCreateWidget ( ) call, making the code easier to 
read. (However, it is still more difficult to read than when using the varargs interfaces.) 

Example 3-18. Setting the argument list with XtSetArg 
int i; 
Arg args [ i0 ] ; 
/* XtAppInitialize may be called before or after the XtSetArg calls */ 
i=0; 
XtSetArg(args[i], XtNcallback, (XtArgVal) quit_callback_list); i++; 
XtSetArg(args[i ], XtNsensitive, (XtArgVal) True) ; i++; 
banner = XtCreateManagedWidget ( 
banner, /* widget name * / 
conmandWidgetClass, /* widget class from Label.h */ 
toplevel, /* parent widget */ 
args, /* argument list */ 
i) ; /* arg list size from XtSetArg counter */ 
Notice that i is used as the number of arguments in the XtCreateManagedWidget ( ) 
call, not XtNumber (). XtNumber() would in this case return the value 10, the total 
length of the Arg array. 
Remember that i must be incremented outside the macro, because XtSetArg ( ) references 
its first argument twice. The following code will not work because XtNresource2 will be 
set into widget_args [2] instead of widget_args [1], as desired. Example 3-19 
shows you how not to use XtSetArg ( ). 
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3.8 More About Application Contexts 

We have used application contexts in the examples so far, but not discussed what they really 
are or what they are for. 
An application context is a structure maintained by Xt that stores all the data associated with 
the application, including the functions registered by the application and other information 
about the application. Primarily, its purpose is to allow Xt applications to run without modi- 
fication on certain operating systems that do not have a separate address space for each pro- 
cess. These systems include the Xerox Cedar environment, the Symbolics Genera environ- 
ment, and the TI Explorer system. Although systems like this are not common, the goal of all 
X software in C is to be portable to any system that supports C." 
Why then is the XtAppContext exposed in the programming interface? It is possible, 
though difficult, to create more than one application context within a single program. This is 
rarely done and its implications are complex, so we will reserve discussion of it until Section 
14.10. 
The important thing to remember is that for maximum portability, you need to use the ver- 
sions of routines that begin with XtApp instead of those that don't. For instance, use Xt- 
AppInitialize ( ) instead of XtInitialize (), and use XtAppMainLoop ( ) not 
XtMainLoop ( ). 
Of the routines you have seen so far in this book, only XtVaAppInitialize (), XtApp- 
Initialize (), XtAppMainLoop (), and XtAppAddActions ( ) use explicit applica- 
tion contexts. The complete list of routines that have equivalents is presented in Section 
14.10. 
Throughout this book we will continue to use the routines that use the explicit application 
context. 

% It is almost a maxim that there is no such thing as portable software, only software that has been ported. The goal 
(and more or less the reality) of X is that the porting process should be much easier than it has traditionally been, and, 
most important, that only one version of a particular piece of software should need to be maintained. The various 
idiosyncrasies of particular compilers can be dealt with using conditional preprocessor directives (#ifdef). X features 
were designed specifically to provide ways to handle differences in screens and keyboards. The application context 
is an effort to provide a way to handle odd operating systems. 
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4 

An Example Application 

This chapter describes a complete application, in several iterations. First, it 
shows a simple version of the program, a bitmap editor, as it would be written 
assuming the existence of a BitmapEdit widget (which is actually developed 
in Chapters 6 and 7). Then, two refined versions are developed, each 
demonstrating additional Toolkit programming techniques. Finally, the same 
application is shown as it would be written if the bitmap editor were imple- 
mented in an application window rather than with the BitmapEdit widget. 

In This Chapter: 

xbitmapl : Bitmap Editor Using a BitmapEdit Widget ......................... 102 
Widget Public Functions ................................................................. 105 
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this application entirely with existing widgets and application code, how to implement it 
using custom widgets, and how to implement a mixture of the two. 

4.1 xbitmapl" Bitmap Editor Using a BitmapEdit Widget 

The screen appearance of xbitmapI is shown in Figure 4-1. As usual, it is a good idea to 
compile and run each example as it is discussed. 

_) 

mmm 
mmm 
mmm 

Figure 4-1. xbitmap 1: how it looks on the screen 

The BitmapEdit widget lets you set bits in the visible bitmap by clicking the first pointer but- 
ton or dragging the pointer with the first button held down, lets you erase bits using the sec- 
ond button, or lets you toggle bits using the third button. The "Print Output" button simply 
prints on the standard output an array of 1 's and O's representing the set and unset bits in the 
bitmap. (Code to read and write standard X11 bitmap files is added in a later version.) 
Scrollbars are available so that large bitmaps can be edited, but they are not displayed unless 
needed. 

How to get and compile the example source code is described in the Preface and Section 2.3.2. 
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xbitmapl consists of only six widgets other than the top-level Shell; one Form, one Box, one 
Viewport, one BitmapEdit, and two Command widgets. The Form widget is the child of the 
Shell widget. One child of the Form widget is a Box containing the two Command widgets, 
and the other is the Viewport widget. The BitmapEdit widget is the sole child of the 
Viewport. This arrangement of geometry-managing widgets keeps the appearance of the 
application neat even when the application is resized, and displays scrollbars when the appli- 
cation is too small to display the entire bitmap. 

The code for xbitmapl is shown in Example 4-1. One new technique shown in this example 
is the use of the public function BitraapEditGetArrayString defined by the Bitmap- 
Edit widget. This function allows an application callback function to access the BitmapEdit 
widget's private data. Even though the array of bits in the bitmap is a resource of the 
BitmapEdit widget that can be read with XtGetValues (), this public function provides a 
more convenient way for the application to get the contents of the bitmap so that it can print 
them out (or later, write them to a file). 

Example 4-1. xbitmap 1: complete code 
* xbitmapl, c 
*/ 
#include <stdio.h> 
#include <Xll/Intrinsic .h> 
#include <Xll/StringDefs .h> 

#include <Xll/Xaw/Form.h> 
#include <Xll/Xaw/Box.h> 
#include <Xll/Xaw/Ccm%nd.h> 
#include <Xll/Xaw/Viewport.h> 

#include "BitmapEdit.h" 

Dimension pixmap_width_i_cells, pixmap_height_i_cells; 

/* 
* The printout routine prints an array of is and 0s representing the 
* contents of the bitmap. This data can be processed into any 
* desired form, including standard XII bitmap file format. 
*/ 
/*ARGSUSED */ 
static void 
Printout(widget, client_data, call_data) 
Widget widget; 
XtPointer client_data; /* cast to bigBitmap */ 
XtPointer call_data; /* unused */ 
{ 
Widget bigBitmap = (Widget) client_data; 
int x, y; 
char *cell; 
cell = BitmapEditGetArrayString(bigBitmap); 

(void) putchar('\n'); 
for (y = 0; y < pixmap_height_ir_cells; y++) { 
for (x = 0; x < pixmap_width_izl_cells; x++) 
(void) putchar(cell[x + y * pixmap_width_in_cells] ? 'i" : "0'); 
(void) putchar('\n'); 
} 
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Example 4-1. xbitmapl : complete code (continued) 

(void) putchar('\n'); 

main(argc, argv) 
int argc; 
char *argv[]; 
{ 
XtAppContext app_context; 
Widget topLevel, form, buttonbox, quit, output, viewport, bigBitmap; 

/* never call a Widget variable "exit"! */ 
extern exit(); 

static XrnOptionDescRec table[ ] = { 
{"-pw", "*pixmapWidthInCells", XrmoptionSepArg, NULL}, 
{"-pixmapwidth", "*pinapWidthInCells", XrnptionSepArg, NULL}, 
{"-ph", "*pixmapHeightInCells", XrnptionSepArg, NULL}, 
{"-pixmapheight", "*pixmapHeightInCells", XrmoptionSepArg, NULL}, 
{"-cellsize", "*cellSizeInPixels", XrnptionSepArg, NULL}, 

}; 

topLevel = XtVaAppInitialize( 
&app_context, /* Application context */ 
"XBitmapl", /* Application class */ 
table, XtNumber(table), /* conmand line option list */ 
&argc, argv, /* conmnnd line args */ 
NULL, /* for missing app-defaults file */ 
NULL); /* terminate varargs list */ 

form = XtVaCreateManagedWidget("form", formWidgetClass, 
topLevel, NULL); 

buttonbox = XtVaCreateManagedWidget("buttonbox", boxWidgetClass, 
form, NULL); 

output = XtVaCreateManagedWidget("output", conmandWidgetClass, 
buttonbox, NULL); 

/* callback added belowafterbig bitmap is created */ 

quit = XtVaCreateManagedWidget("quit", conmandWidgetClass, 
buttonbox, NULL); 

XtAddCallback(quit, XtNcallback, exit, NULL); 

viewport = XtVaCreateManagedWidget("viewport", 
viewportWidgetClass, form, NULL); 

bigBitmap = XtVaCreateManagedWidget("bigBitmap", 
bitmapEditWidgetClass, viewport, NULL); 

XtAddCallback(output, XtNcallback, Printout, bigBitmap); 

/* need the following values for the printout routine. */ 
XtVaGetValues(bigBitmap, 
XtNpixmapWidthInCells, &pixmap_width_irL_cells, 
XtNpixmapHeightInCells, &pixmap_height_in_cells, 
NULL); 
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4.2 xbitmap2 and xbitmap3: Adding Graphics to Display the 
Bitmap 

In addition to displaying the bitmap in editable form, with one cell for each pixel in the 
actual bitmap, a bitmap editor should also display an image in true scale that shows what the 
bitmap really looks like when displayed on the screen. It is customary to present this bitmap 
in both normal and reverse video, and update it every time the user toggles a cell in the 
enlarged bitmap. Figure 4-2 shows the appearance of the application with this feature added 
There are two ways to implement this behavior. One is to use the Label widget, which can 
display a pixmap instead of a string. The other is to draw into a Core widget. From the point 
of view of the user, both would look exactly the same. 

grite File I 

Figure 4-2. xbitmap2 and xbitmap3: true-scale normal and reverse bitmaps added 

Implementing this feature with Label widgets is straightforward; the application creates two 
pixmaps of the proper size, and sets the Xt:lpixmap resources of two Label widgets to dis- 
play them. The problem comes when trying to update this display each time a cell is toggled. 
We can easily draw the changed pixel into the small pixmaps, but without a push the Label 
widget won't redisplay the pixmap. Because the Xt:lpim'nap resource is not changing--the 
same pixmap ID is used for the life of the application rathe Label widget is not notified by Xt 
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that the pixmap has been drawn into. There are two ways to make the existing Label widget 
redraw the pixmap. One is to clear its window using an Xlib routine (XCiear/indow ( ) ) 
that generates an Expose event, which will then cause Label to redraw the widget. But this 
causes the pixmap to flash annoyingly every time a pixel is changed, since the server clears 
each window to its background color before the pixmap is redrawn. If you would like to see 
this problem, and the code to implement this approach, compile and run xbitmap2. The sec- 
ond method, which avoids the flashing problem, is to synthesize an Expose event (create an 
XExposeEvent structure and fill it with values) and send it to the Label widget using 
XSendEvent (). This is a bit of a kludge but it works. The code implementing this 
improved approach is commented out in the redraw_small_picture subroutine in 
xbitmap2. You may wish to uncomment the XSendEvent () code, comment out the 
XClearWindow ( ) call, and retry the example to see that it stops the flashing. 

The source of this (surmountable) problem is that the Label widget is designed for static pix- 
maps. If it provided a public function called XawLa]eiledrawPixltlap (), we could 
more cleanly correct the flashing bug. Although adding this function to the widget code 
would be easy, we could no longer call the remaining widget class Label. We would be 
creating a new widget class. (Some widget sets do define two separate widget classes: one 
for displaying static pixmaps, and the other for dynamic, editable pixmaps.) 

An alternate approach is to create Core widgets for each small pixmap and draw into them 
from the application, as illustrated in Figure 4-3. This way we can redraw each pixmap with- 
out clearing the window in between each update, eliminating the flash. We can consider this 
approach because these small pixmap widgets have no input semantics and simple output 
semantics and should be easy to implement. 

Application draws to pixmap only... 

i 
...then copies pixmap to widget window. 

Figure 4-3. Application draws into Pixmap and copies it to widget window 

Three new routines are needed: iRedrawSmallPicture, SetUpThings, and Cell- 
Toggled. These three routines are primarily composed of Xlib calls that set up for and per- 
form graphics. The iRedrawSmallPicture routine copies a pixmap into a widget, Set- 
UpThings creates the pixmaps and the GCs (introduced in the next subsection, 4.3.1) 
needed to draw into these pixmaps, and CellToggled is a callback function registered 
with the BitmapEdit widget that updates the pixmaps whenever a cell is toggled. Code is 
also added to main to create the two Core widgets and give them translations so that they are 
redrawn on Expose events. We'll show these routines one at a time. Example 4-3 shows 
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The main routine arranges for the RedrawSmallPicture routine to be called whenever 
an Expose event arrives for either Core widget, and registers the CellToggled callback 
with the BitmapEdit widget. These routines depend on the setup performed in Set- 
UpThings. 

' 4.2.1 

Graphics from the Application 

Drawing in the X Window System is done by creating a graphics context (GC) that specifies 
such things as colors and line widths, and then calling a drawing routine that specifies what 
shape is to be drawn. These two steps are basic to X and required in programs written in any 
language with or without a toolkit. For example, the call to draw a line specifies only the 
start and endpoints of the line. The GC specifies everything else about how the server will 
actually draw this line. 

A GC is a server-side object that must be created by the application. The purpose of the GC 
is to cache on the server side information about how graphics are to be executed by the 
server, so that this information doesn't have to be sent over the network with every graphics 
call. If X did not have GCs, every graphics call would have many arguments and this would 
waste network time (and be annoying to program). Instead, you create a small number of 
GCs before drawing (in the startup phase of the application). Each represents a particular 
color or line style you will need to draw with at some point. You then specify one of these 
GCs in each call to draw. For example, to draw text and be able to highlight it at will, it is 
customary to create two GCs, one for drawing in white on black, and one for drawing in 
black on white (where colors can be substituted for black and white on color screens). 

Once created, a GC is referred to by its ID, of type GC. This ID is specified in calls to draw 
using that GC. 

From the application, the Xlib routine XCreateGC ( ) is usually used to create GCs. Xt also 
provides the XtGetGC ( ) routine for creating GCs, but it is typically used only inside widget 
code when there could be many of the same GCs created. XtGetGC ( ) is very similar to 
XCreateGC(), except that it arranges for GCs to be shared among widgets (within one 
application). XtGetGC ( ) will be described in Section 7.2.1. 

In xbitmap3, the SetUpThings routine is responsible for creating two pixmaps that act as 
off-screen drawing surfaces, and two GCs that will be used to draw and undraw pixels in the 
pixmaps. Whenever the widgets need to be updated, the pixmaps are copied into the widgets. 
This is only one possible exposure-handling approach. Another is to draw the required points 
directly into the widgets each time they need to be updated, keeping a record of the drawn 
points so that the entire widget can be redrawn in case of exposure. Example 4-4 shows 
SetUpThings, which creates pixmap and GCs and then initializes the pixmaps. 

Example 4-4. xbitmap3: creating pixmaps and GCs 
static void 
SetUpThings (w) 
Widget w; 
{ 
XCValues values; 
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Example 4-4. xbitmap3: creating pixmaps and GCs (continued) 
bitmap_stuff .normal_bitmap = XCreatePixmap (XtDisplay (w), 
RootWindowOfScreen (XtScreen (w)), 
bitmap_stuf f. pixmap_width_in_cells, 
bitmap_stuff .pixmap_height_in_cells, i) ; 
bitmap_stuff, reverse_bitmap = XCreatePixmap (XtDisplay (w), 
RootWindowOfScreen (XtScreen (w)), 
bitmap_stuf f. pixmap_width_in_cells, 
bitmap_stuff.pixmap_height_in_cells, i) ; 
values, foreground = 1; 
values.background = 0; 
/* note that normal_bitmap is used as the drawable because it 
* is one bit deep. The root window may not be one bit deep */ 
bitmap_stuff.draw_gc = XCreateGC (XtDisplay (w), 
bitmap_stuf f. normal_bitmap, 
GCForeground I GCBackground, &values); 
values.foreground = 0; 
values.background = i; 
bitmap_stuff .undraw_gc = XCreateGC (XtDisplay (w), 
bitmap_stuf f. normal_bitmap, 
GCForeground I GCBackground, &values); 
/* pixmaps must be cleared - may contain garbage */ 
XFillRectangle (XtDisplay (w), 
bitmap_stuf f. reverse_bitmap, bitmap_stuf f. draw_gc, 
0, 0, bitmap_stuff.pixmap_width_in_cells + i, 
bitmap_stuff.pixmap_height_in_cells + i); 
XFillRectangle (XtDisplay (w), 
bitmap_stuf f. normal_bitmap, bitmap_stuf f. undraw_gc, 
0, 0, bitmap_stuff.pixmap_width_in_cells + i, 
bitmap_stuff.pixmap_height in cells + i); 
} 
Notice that GCs can only be used on windows or pixmaps with the same depth as the window 
or pixmap that is passed in the call to create the GC. In this case, the pixmaps created con- 
tain only one plane, even when running on a server with a color screen. These pixmaps are 
passed to XCreateGC ( ) to set the depth of the GCs. These GCs can only be used to draw 
into the single plane pixmaps. As you will see in Example 4-6, a separate GC (the default 
GC) is used to copy from the pixmaps into the windows, since on color screens the windows 
have multiple planes. (You know you have done this incorrectly if you get an error only on 
color screens.) 
Xt does not provide drawing calls of its own. You must call Xlib directly to draw. An Xlib 
drawing routine is known as a primitive. Under X, text is drawn by a graphics primitive, just 
as lines, arcs, and other graphics are drawn. 
Colors are normally specified by the user as strings such as "blue," but the X server under- 
stands colors only when specified as numbers called pixel values. A pixel value is used as an 
index to a lookup table called a colormap, which contains values for the RGB (red-green- 
blue) primaries used to generate colors on the screen. However, a particular pixel value does 
not necessarily always map to the same color, even when run twice on the same system, 
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points into the pixmaps according to the information passed in, and then calls Redraw- 
SmallPicture to copy the pixmaps into each Core widget. 

The first line of CellToggled casts the generic pointer info into the structure type 
defined by BitmapEdit, BitmapEditPointInfo. Under most compilers this can also be 
done (perhaps more clearly) by declaring the info argument as type BitmapEditPoint- 
Info in the first place. However, ANSI C compilers require a cast. 

The RedrawSmal i Picture routine is shown in Example 4-6. 

Example 4-6. xbitmap3: the RedrawSmallPicture routine 
/*ARGSUSED* / 
static void 
RedrawSmallPicture(w, event, params, num_params) 
Widget w; 
XEvent *event; 
String *params; 
Cardinal *num_params; 
{ 
Pixmap pixmap; 
if (w == bitmap_stuff, showNormalBitmap) 
pixmap = bitmap_stuff.normal_bitmap; 
else 
pixmap = bitmap_stuff, reverse_bitmap; 
if (DefaultDepthOfScreen (XtScreen (w)) == i) 
XCopyArea (XtDisplay (w), pixmap, XtWindow (w), 
DefaultGCOfScreen(XtScreen(w) ), 0, 0, 
bitmap_stuf f. pixmap_width_in_cel i s, 
bitmap_stuf f. pixmap_height_in_cel i s, 
0, 0); 
else 
xCopyPlane (XtDisplay (w), pixmap, XtWindow(w), 
DefaultGCOfScreen(XtScreen(w) ), 0, 0, 
bitmap_stuf f. pixmap_width_in_cel is, 
bitmap_stuf f. pixmap_height_in_c e i i s, 
0, 0, i); 
RedrawSmallPicture is called from CellToggled, and also by Xt in response to 
Expose events because we registered it as an action and specified it in the translation table 
resource of each of the Core widgets. (This is described in detail in the next section.) 
The use of one of two Xlib routines, depending on the depth of the screen, is an optimization. 
XCopyArea ( ) is faster, but can be used for this job only on monochrome displays, because 
the pixmaps used here are one plane deep on all displays and must be translated into multiple 
planes with XCopyPlane ( ) on color displays. 
See Volume One, Xlib Programming Manual, for details. 
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4.2.2 Writing a Bitmap File 

Once we have pixmaps in our application that contain the current bitmap, it is a trivial matter 
to change the printout callback function to write a bitmap file instead of just printing an 
array of ones and zeroes to the standard output. This is easy because there is an Xlib func- 
tion, XWr-i teB-i traapF-i l e (), that writes the contents of a single-plane pixmap into a file. 
Example 4-7 shows the code that gets a filename from the command line and then writes the 
bitmap file. 

Example 4-7. xbitmap3: writing a bitmap file 
/* ARGSUSED * / 
static void 
Printout (widget, client_data, call_data) 
Widget widget; 
XtPointer client_data, call_data; /* unused */ 
{ 
XWriteBitmapFile (XtDisplay (widget), bitmap_stuff, filename, 
bitmap_stuf f. normal_bitmap, 
bitmap_stuf f. pixmap_width_in_cel is, 
bitmap_stuff.pixmap_height_in_cells, 0, 0) ; 
} 

main (argc, argv) 
int argc; 
char *argv[ ] ; 
{ 

/* XtAppInitialize */ 

if (argv[l] != NULL) 
bitmap_stuff.filename = argv[l]; 
else { 
fprintf(stderr, "xbitmap: must specify filename\ 
on conmand line.\n"); 
exit(l); 
} 

} 
Contrast this version of Printout to the one shown in Example 4-1. 
Note that reading a bitmap file requires some more complicated Xlib programming, not Xt 
programming, so we will not take the space to describe it. If you are curious, the complete 
code for xbitrnap5, which both reads and writes bitmap files, is shown in Appendix E, The 
xbitmap Application. 
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4.2.3 Actions 

So far in the book we have used callbacks to link widgets with application code. Callbacks 
are the most common way of linking the application with the user interface. 
But when you are implementing a custom window, callbacks are useless because they are 
defined by each widget class, and none of the existing widget classes has the callbacks or fea- 
tures that you need. 
Therefore, you need to use a different technique for linking application code with widget 
code: the combination of actions and translations. You can use actions to add features to a 
Core widget. (Actions are also used inside widget code to implement widget features.) 
The action and callback techniques for linking the application with the user interface differ 
in the way that the registered function is invoked. For callbacks, the trigger is an abstract 
occurrence defined by the widget, which may or may not be event related. When this hap- 
pens, the routines on one of a widget's callback lists are invoked by the widget code, using a 
call to XtCallCallbacks () or XtCallCallbackList (). Actions, on the other 
hand, are invoked directly by Xt's translation mechanism, as the result of an event combina- 
tion. 
In xbitmap3 we will make the RedrawSrnallPicture function into an action function 
instead of a callback function (this means just giving it different arguments). Then we need 
to arrange for Xt to call RedrawSrnallPicture whenever one of the Core widgets 
becomes exposed. The general procedure for arranging this is the same as for call- 
backs--you register the function during the setup phase of the application, and then Xt will 
call it in response to Expose events. Registering an action, though, is quite different from 
registering a callback. 
To register the action, you first declare an actions table, which maps action name strings to 
action function pointers. Then you must register the actions table with Xt by calling Xt- 
AppAddActions (). Finally you create a translation table and store it in the app-defaults 
file or hardcode it in the application. A translation table is a widget resource which contains 
a mapping between events or event sequences and action names. Figure 4-4 shows a 
translation table and an action table, and shows how each is used in the process of mapping 
events to action function calls. (The format of these two tables is described in the following 
sections and in Chapter 8, Events, Translations, and Accelerators.) This two-stage mapping 
is necessary so that translations can be specified in resource files. Since resource files contain 
only strings, a translation specified in a resource file can only translate an event into an action 
name. The action table, which can only be specified in the code, translates the action name 
into the actual action function pointer. 
When an event arrives in a particular widget, Xt searches that widget's translation table 
resource. If that event is not found in the table, Xt does nothing. If the event is found, the 
matching action name is searched for in the action table. If the action name is found, the 
corresponding action function is called. 
We'll describe the format of the action table and translation table, using xbitmap3 as an 
example. 
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Action names and action functions should not start with Xt or xt: these are reserved for the 
Intrinsics. 

Example 4-8 shows the code from bitmap3 that creates the action table and registers it with 
XtAppAddActions (). 

Example 4-8. xbitmap3.c: adding a feature to a Core widget 
main (argc, argv) 
int argc; 
char **argv; 
{ 
/* other declarations */ 

static XtActionsRec actions[ ] = { 
{ "RedrawSmallPicture", RedrawSmallPicture}, 
}; 

/* XtAppInitialize */ 

XtAppAddActions (app_context, actions, XtNumber (actions)) ; 

I* XtAppMainLoop *I 
} 
Actions defined by a widget class are usable only by all instances of that widget class. 
Actions added with XtAppAddAct ions ( ), on the other hand, are global to the application 
context, and therefore usable by any widget instance of any class in the application. Which 
widgets they are actually used with is defined by the translation table, as described below. 
The names of widget class actions and application actions do not conflict. For example, if an 
application were to define an action called Move, and some widget class already has an 
action by that name, the two actions would not conflict with each other. 
When you map the action to events in a particular widget (using a translation table), the same 
is true, with a slight caveat. If you write an action called Move, and the widget you install it 
on already has a Move action, your version will be ignored. This implies that you are trying 
to replace a widget action with your own, and this is not allowed. You have to write a 
subclass of the widget to replace a widget action. 
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4.2.4 Translations 

Once you have an action table registered, those actions are ready to be used by any widget in 
the application. But which widgets will they be used in, and which will trigger them? 
Translations determine these things. 

You need to set a translation table resource, XtNtranslations, on any widget you want 
to be able to call an application action. In the case of xbitmap3, we want RedrawSmall- 
Picture to be called when Expose events occur in the widgets that are displaying the 
small pixmaps. This means that we need to set the XtNtranslations resource on those 
two widgets, and the value of the resource should be a translation that maps an Expose 
event into a RedrawSmallPicture call. 

4.2.4.1 

The Translation Table 

Every widget that contains actions also has a default translation table that maps event 
combinations into those actions. The application can override, augment, or replace this table 
to make a widget call application-registered actions in addition to the widget's own actions. 
Registering actions with XtAppAddActions () makes them eligible for inclusion in 
translation tables. 
Each line of a translation table maps a sequence of events to a sequence of actions. The 
entire translation table is simply a string consisting of one or more event specifications in 
angle brackets, with optional modifiers, followed by a colon and a function name string 
defined in an action table. Multiple translations can be specified as part of the same string. 
By convention, the string is continued on several lines, one for each translation, each line 
except the last terminated with a linefeed (\n) and a backslash (\). 
We'll describe the details of event specification and other aspects of translation table syntax 
in Chapter 8. Events, Translations, and Accelerators. For now, an example should get the 
point across quite clearly. 
The translation we need for xbitmap3, as it would appear in the application code, is shown in 
Example 4-10. This example also shows how the translation table must be converted into an 
internal form with XtParseTranslationTable() before it can be used to set an 
XtNtranslations resource. 

Example 4-10. A simple translation table 
XtTranslations mytranslations; 
static char transTable[ ] = 
"<Expose>: RedrawSmallPicture ( ) "; 

bitmap_stuff, showReverseBitmap = 
XtVaCreateManagedWidget ( "showReverseBitmap", 
coreWidgetClass, frame2, 
XtNtranslations, XtParseTranslationTable (transTable) ; 
XtNwidth, bitmap_stuf f. pixmap_width_irL_cel i s, 
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4.2.4.3 Action Parameters 

The params and num-params arguments of an action function are passed in from the 
translation table by Xt. For example, consider an action called Move, which can move some 
data left of right. A translation table that selects events that will invoke Move is shown in 
Example 4-14. 

Example 4-14. A translation table with action parameters 
*tetris. translations: \n\ 
<Key>Left: Move(l) \n\ 
<Key>Right : Move (r) 

With this translation table, Move will be passed a param argument 'T' when the left arrow 
key is pressed, and "r" when the right arrow key is pressed. 

4.2.5 

Adding Actions to Existing Widgets 

It is also possible to add actions to widgets other than Core but it takes more care. Usually, 
when a widget does not provide a certain callback you want associated, it also does not pro- 
vide various other characteristics that you want. For example, to make the Label widget 
work like Command (pretending that the Command widget didn't already exist), you would 
have to make it accept more kinds of input, add the drawing code to highlight the border and 
draw the window darker to simulate shadow, and add the ability to call an application func- 
tion. All of this can be done with actions, but it would take a lot of work. What can make it 
difficult is that your code may interact with the widget's code in unpleasant ways. When the 
changes are major, it makes more sense to create a new widget subclass that shares some 
characteristics and code with its superclass. As we will see, that is exactly how Command is 
implemented, as a subclass of Label. The Core widget, on the other hand, has no input or 
output semantics at all. and therefore it is simpler to add actions to it without conflict. 

4.3 

xbitmap4" A Bitmap Editor Without a BitmapEdit Widget 

Until you have experience working with widget code, it can be easier to prototype a custom 
window for your application by adding to a Core widget from the application code. Once 
this code is working, and you have read Chapter 6, Inside a Widget, and Chapter 7, Basic 
Widget Methods, you can easily move the code into a widget when you want to package it or 
take advantage of any of the features of Xt that are inaccessible from the application. The 
code for the BitmapEdit widget was originally written as an application (as described in this 
section) and later moved into a widget (with the result described in Chapters 6 and 7). Once 
you understand the structure of a widget, it becomes easier to write widgets directly than to 
build the same functionality in the application first. 

The xbitmap4 implements an application almost identical to xbitmapl, but without using the 
BitmapEdit widget. The custom bitmap editing window is done in a Core widget, with all the 
code in the application. This application is a culmination of everything you have seen so far. 

122 X Toolkit Intrinsics Programming Manual Athena Edition 
-. 



It is also a preview of what you will see in the next chapter. The same code in xbitmap4 that 
is used to implement the bitmap editor will be moved into widget code in Chapters 6 and 7. 

This example takes advantage of application resources to set the configurable parameters of 
the bitmap code. The code that sets up the application resources is described in Section 3.6. 
When moving the code into a widget framework, the same resource list will be used verba- 
tim. The example also provides command-line options to set the important parameters of the 
bitmap code. The code for processing these options is described in Section 3.7. The code is 
the same whether used for setting application resources or widget resources, except no call 
equivalent to XtGetAppl icationResources ( ) is necessary in a widget. 

The exposure strategy used for the bitmap editor is the same as for the small bitmaps in the 
previous section. The application creates a large pixmap of depth one that stores the current 
image of the bitmap being edited. Whenever the screen needs updating, the applicable part 
of the pixmap is copied to the Core widget in the Redraw_p'i cture routine. Because this 
pixmap is much bigger than the ones in the last section, it is an important optimization that 
only the required parts of the pixmap are copied. (This is not the only possible exposure 
strategy. This particular strategy has very low network load, but uses a relatively large 
amount of server memory. For this reason it is not ideal for PC servers.) 

The SetUpThings routine creates the pixmap, draws a grid into it that will persist for the 
life of the application, and creates three GCs. One GC is for copying from the pixmap to the 
window, and two are for drawing and undrawing cells in the pixmap. The btn._event rou- 
tine draws and undraws cells in the pixmap according to pointer clicks and drags, and calls 
Redraw_picture to update the Core widget display. 

Redraw_picture is called both from the application and from Xt. This is a common trick 
used to reduce the duplication of drawing code. Since Redraw._picture is an action, it 
has an event argument that is used by Xt to pass in the Expose event describing the area ex- 
posed. This application also uses this argument by constructing a fake event to pass in infor- 
mation about which part of the widget to draw. 

The application adds actions and sets the XtNtranslations resource of the Core widget 
so that Xt calls the application routine Redraw._picture whenever Expose events ar- 
rive, and calls bt n_event when But t onPres s or Mot ior2qot i fy events arrive. 

Example 4-15 shows the complete code for xbitmap4. You have seen all the techniques here 
in various examples before. You should work through the code and make sure you under- 
stand the purpose of each section. However, don't worry about the details of the Xlib calls, 
since they are specific to this application. 

Example 4-15. xbitmap4 : implementing the bitmap editor from the application 
#include <Xll/Intrinsic .h> 
#include <Xll/StringDefs .h> 
#include <XII/Xaw/Paned.h> 
#include <XII/Xaw/Box.h> 
#include <Xl l / Xaw / C carnand . h> 
#include <stdio.h> 

/* 
* The following could be placed in an "xbitmap.h" file. 
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Example 4-15. xbltmap4 : implementing the bitmap editor from the application (continued) 

*/ 
#define XtNdebug "debug" 
#define XtCDebug "Debug" 
#define XtNpixmapWidthInCells "pixmapWidthInCells" 
#define XtCPixmapWidthInCells "PixmapWidthInCells" 
#define XtNpixmapHeightInCells "pixmapHeightInCells" 
#define XtCPixmapHeightInCells "PixmapHeightInCells- 
#define XtNcellSizeInPixels "cellSizeInPixels" 
#define XtCCellSizeInPixels "CellSizeInPixels" 
#define DRAWN 1 
#define UNDRAWN0 
#define DRAW 1 
#define UNDRAW 0 
#define MAXLINES i000 
#define MINBITMAPWIDTH 2 
#define MAXBITMAPWIDTH i000 
#define MINBITMAPHEIGHT 2 
#define MAXBITMAPHEIGHT i000 
#define MINCELLSIZE 4 
#define MAXCELLSIZE i00 
#define SCROLLBARWIDTH 15 
typedef struct { 
Pixmap big_picture; 
GC drawc, undrawc; /* for drawing into big_picture, 1-bit deep */ 
GC copy_gc; /* for copying from pixmap into window, screen depth */ 
char *cell; /* keeps track of cells drawn */ 
Widget bitmap; /* drawing surface */ 
int cur_x, cur_y; 
Dimension pixmap_width_in_pixels, pixmap_height_in_pixels; 
} PrivateAppData; 
/* data structure for application resources */ 

typedef struct { 
Pixel copy_fg; 
Pixel copy_bg; 
int pixmap_width_in_cells; 
int pixmap_height in cells; 
int cell_size_in_pixels; 
Boolean debug; 
} AppData, *AppDataPtr; 
AppData app_data; 
PrivateAppData private_app_data; 
/* resource list */ 
static XtResource resources[] = { 
{ 
XtNforeground, 
XtCForeground, 
XtRPixel, 
sizeof(Pixel), 
XtOffsetOf(AppData, copy_fg), 
XtRString, 
XtDefaultForeground 
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Example 4-15. xbitmap4 : implementing the bitmap editor from the application (continued) 
}, 
{ 
Xt]',ckgrotmd, 
XtCEckgound, 
XtRPixel, 
sizeof (Pixel), 
XtOffsetOf (AppData, copy_bg), 
XtRSt ring, 
XtDe faultBackground 
], 
{ 
XtNpixmapWidthInCel is, 
XtCPixmapWidthInCel is, 
XtRInt, 
sizeof (int), 
XtOffsetOf (AppData, pixmap_width_in_cells), 
XtRInate, 
(XtPointer) 32, 
}, 
{ 
XtNpixmapHeight InCel i s, 
XtCPixmapHeight InCel is, 
XtRInt, 
sizeof (int), 
XtOf fsetOf (AppData, pixmap_height_in_cel i s ), 
XtRInediate, 
(XtPointer) 32, 
], 
{ 
XtNcel iSi zeInPixels, 
XtCCel 1 SizeInPixels, 
XtRInt, 
sizeof (int), 
XtOffsetOf (AppData, cell_size_in_pixels), 
XtRInmediate, 
(Xt Pointer) 30, 
], 
{ 
XtNdebug, 
XtCDebug, 
XtRBoolean, 
sizeof (Boolean), 
XtOffsetOf (AppData, debug), 
XtRInmediate, 
(Xt Pointer) FALSE, 
], 

/* Command-line options table */ 
static XtionDescRec options[] = { 
{ "-pw", "*pixmapWidthInCells', 
{ "-pixmapwidth', "*pixmapWidthInCells', 
{ "-ph', "*pixmapHeightInCells', 
{ "-pixmapheight', "*pixmapHeightInCells", 
{ "-cellsize', "*cellSizeInPixels', 

XrmoptionSepArg, NULL ], 
XrmoptionSepArg, NULL ), 
XrmoptionSepArg, NULL ], 
XrmoptionSepArg, NULL ], 
XrmoptionSepArg, NULL ], 
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Example 4-15. xbitmap4: implementing the bitmap editor from the application (continued) 
RootWindowOfScreen (XtScreen (w)), 
private_app_data, pixmap_wi dth_in_pixel s, 
private_app_data.pixmap_height_in_pixels, I) ; 
values, foreground = 1; 
values.background = 0; 
values.dashes = 1; 
values.dash_offset = 0; 
values.line_style = LineOnOffDash; 

private_app_data.draw_gc = XCreateGC(XtDisplay(w), 
privat e_app_data, big_pi cture, 
GCForeground I GCBackground I GCDashOffset I GCDashList I 
GCLineStyle, &values); 

values, foreground = 0; 
values .background = 1; 
private_app_data, undraw_gc = XCreateGC (XtDisplay (w), 
privat e_app_data, big_picture, 
GCForeground I GCBackground I GCDashOffset I GCDashList I 
GCLineStyle, &values) ; 

values, foreground = app_data, copy_fg; 
values .background = app_data, copy_bg; 
private_app_data, copy_gc = XCreateGC (XtDisplay (w), 
RootWindowOfScreen (XtScreen (w)), 
GCForeground I GCBackground, &values); 

XFillRectangle (XtDisplay (w), private_app_data.big_picture, 
private_app_data.undraw_gc, 0, 0, 
private_app_data, pixmap_width_in_pixel s, 
private_app_data, pixmap_height_in_pixel s ) ; 

/* draw permanent grid into pixmap */ 
n_horiz_segments = app_data.pixmap_height in cells + i; 
n_vert_segments = app_data.pixmap_width_in_cells + i; 

for (x = 0; x < n_horiz_segments; x += I) { 
segment[x].xl = 0; 
segment[x].x2 = private_app_data.pixmap_width_in_pixels; 
segment[x].yl = app_data.cell_size_in_pixels * x; 
segment[x ].y2 = app_data.cell_size_in_pixels * x; 
} 

/* drawn only once into pixmap */ 
X DrawSegments(XtDisplay(w), private_app_data.big_picture, 
private_app_data.draw_gc, segment, n_horiz_segments); 
for (y = 0; y < n_vert_segments; y += I) { 
segment [y ] .xl = y * app_data.cell_size_in_pixels; 
segment[y] .x2 = y * app_data.cell_size_ir_pixels; 
segment [y ] .yl = 0; 
segment [y ].y2 = private_app_data.pixmap_height_in_pixels; 
} 

/* drawn only once into pixmap */ 
XDrawSegment s (XtDi splay (w), privat e_app_data .big_picture, 
private_app_data.draw_gc, segment, n_vert_segments); 
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Example 4-15. xbitmap4: implementing the bitmap editor from the application (continued) 

/* ARGSUSED * / 
static void 
RedrawPicture(w, event, params, num_params) 
Widget w; 
XExposeEvent *event; 
String *params; 
Cardinal *num_params; 
{ 
register int x, y; 
unsigned int width, height; 
if (event) { /* drawing because of expose or button press */ 
x = event->x; 
y = event->y; 
width = event->width; 
height = event->height; 
} else { /* drawing because of scrolling */ 
x= 0; 
y=0; 
width = I0000; /* always the whole window: */ 
height = I0000; 
} 

if (DefaultDepthOfScreen(XtScreen(w)) :: I) 
XCopyArea(XtDisplay(w), private_app_data.big_picture, 
xtWindow(w), private_app_data.copyc, x + 
private_app_data.cur_x, y + private_app_data.cur, 
width, height, x, y); 
else 
XCopyPlane(XtDisplay(w), private_app_data.big_picture, 
xtWindow(w), private_app_data.copyc, x + 
private_app_data.cur_x, y + private_app_data.cur, 
width, height, x, y, I); 

/* ARGSUSED */ 
static void 
DrawCell(w, event, params, num_params) 
Widget w; 
XButtonEvent *event; 
String *params; 
Cardinal *num_params; 
{ 
DrawPixmaps(private_app_data.drawc, DRAW, w, event); 
} 

/* ARGSUSED */ 
static void 
UndrawCell(w, event, params, num_params) 
Widget w; 
XButtonEvent *event; 
String *params; 
Cardinal *num_params; 
{ 
DrawPixmaps(private_app_data.undrawc, UNDRAW, w, event); 
} 
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Example 4-15. xbitmap4 : implementing the bitmap editor from the application (continued) 

/* ARGSUSED * / 
static void 
ToggleCell(w, event, params, nunt_Darams) 
Widget w; 
XButtonEvent *event; 
String *params; 
Cardinal *nunt_Darams; 
{ 
static int oldx = -i, oldy = -i; 
GC gc; 
int mode; 
int newx = (private_app_data.cur_x + event->x) / app_data.cell_size_in_pixels; 
int newy = (private_app_data.cur__v + event->y) / app_data.cell_size_in_pixels; 
if ((mode = cell [newx + newy * app_data.pixmap_width_in_cells ]) == 
DRAWN) { 
gc = private_app_data.undraw_gc; 
mode = UNDRAW; 
} else { 
gc = private_app_data.draw_gc; 
mode = DRAW; 
} 

if (oldx != newx II oldy != newy) { 
oldx = newx; 
oldy = newy; 
DrawPimaps(gc, mode, w, event); 
} 

/* Private Function */ 
static void 
DrawPixmaps(gc, mode, w, event) 
GC gc; 
int mode; 
Widget w; 
XButtonEvent *event; 
{ 
int newx = (private_app_data.cur_x + event->x) / app_data.cell_size_in_pixels; 
int ney = (private_app_data.cur__v + event->y) / app_data.cell_size_in_pixels; 
XExposeEvent fake_event; 

/* if already done, return */ 
if (cell[newx + newy * app_data.pixmap_width_in_cells] == mode) 
return; 

XFillRectangle(XtDisplay(w), private_app_data.big_picture, 
gc, app_data.cell_size_in_pixels * newx + 2, 
app_data.cell_size in pixels * ney + 2, 
(unsigned int) app_data.cell_size_in_pixels - 3, 
(unsigned int) app_data.cell_size_in_pixels - 3); 

cell[newx + newy * app_data.pixmap_width_in_cells] = mode; 

fake_event.x = app_data.cell_size_in_pixels * newx - private_app_data.cur_x; 
fake_event.y = app_data.cell_size_in_pixels * newy - private_app_data.cur__v; 
fake_event.width = app_data, cell_size_in_pixels; 
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Example 4-15. xbitmap4: implementing the bitmap editor from the application (continued) 
fake_event .height = app_data, cell_size_inpixels; 
RedrawPicture (private_app_data.bitmap, &fake_event) ; 
} 
Of particular interest in the code for xbitmap4 is the Syntax function. Notice that it prints 
out the options that were not understood, in addition to printing out a list of valid options. 
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5 

The Athena Widget Set 

This chapter describes the widgets in the Athena Widget set that have not 
yet been introduced, and provides examples of a few common uses of the 
Text widget. Menu widgets are described in a later chapter. 
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5 
The Athena Widget Set 

This book is primarily about how to program with the Xt Intrinsics, and uses the Athena 
widgets to demonstrate those techniques. This book does not provide a complete manual on 
how to use the Athena widgets. However, this chapter will acquaint you with the default 
appearance and general purpose of the Athena widgets we have not yet used (with the excep- 
tion of menus, which are covered in Chapter 13, Menus, Gadgets, and Cascaded Popups). 
We'll also answer some common questions about how to use the Text widget. With this 
information, you should gain a general idea of the range of widgets you have to choose from. 
Volume Five, X Toolkit Intrinsics Reference Manual provides complete reference informa- 
tion on all the Athena widgets. 

5.1 Simple Widgets 

The Athena widget set provides several useful widgets that haven't yet been presented in this 
book. 

List 

Displays a list of text strings presented in row column format that may be indi- 
vidually selected. When an element is selected an action may take place. A 
List widget is shown in Figure 5-1. 

t Delaware Virginia 

Figure 5-1. A List widget 

Example 5-1 shows the code used to generate the figure above. 
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Example 5-1. Code using the List widget 
#include <Xll/Xaw/List.h> /* Athena List Widget */ 
void DoScmething( ) ; 

main (argc, argv) 
int argc; 
char **argv; 
{ 

static String listitems[ ] = { 
"Delaware" , 
"Virginia", 
"Washington", } ; 
static int nitems = 3; 

list = XtVaCreateManagedWidget( 
"list", /* arbitrary widget name */ 
listWidgetClass, /* widget class frfznLabel.h */ 
topLevel, /* parent widget */ 
NULL); /* terminate varargs list */ 

XawListChange(list, 
listitems, nitems, 
-i, /* List widget calculates longest */ 
True); /* widget should attempt resize */ 

XtAddCallback(list, XtNcallback, DoSomething, 0); 

/* ARGSUSED */ 
void DoSomething(w, client_data, call_data) 
Widget w; 
XtPointer client_data, call_data; 
{ 
XawListReturnStruct *list_struct = (XawListReturnStruct *) call_data; 
printf("Itmnumber %d is the state of %s\n", list_struct->list_index, 
list_struct->string); 
} 

Panner 

A rectangular area containing a slider that may be moved in two dimensions. 
Notification of movement may be continuous or discrete. This widget was pri- 
marily designed for use in the editres application, but it can also be used as an 
alternative to scrollbars. A Panner widget is shown in Figure 5-2, as part of the 
editres application. 

Repeater A push button (which looks just like Command) that triggers an action at an 
increasing rate while the button is held. 
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Toggle 

A push button (like Command) that contains state information. Toggles may 
also be used as radio buttons to implement a "one of many" group of buttons. A 
group of Toggle widgets is shown in Figure 5-4. Example 5-2 and Example 5-3 
show the code and app-defaults file necessary to make a group of Toggle widg- 
ets work as radio buttons as shown in the above figure (where exactly one but- 
ton is always selected). 

Gr'illed I 
Boiled I 

Inclnerat, ed ] 

Figure 5-4. A Toggle widget 

Example 5-2. Toggle buttons used to implement radio buttons 
#include <Xll/Xaw/Toggle.h> /* Athena Toggle Widget */ 

/* ARGSUSED */ 
void Toggled(w, client_data, call_data) 
Widget w; 
XtPointer client_data, call_data; 
{ 
/* call_data unused */ 
String string; 

XtVaGetValues(w, XtNlabel, &string, NULL); 

printf("Custcmerwants meal %s.\n", string); 
} 

maln(argc, argv) 
int argc; 
char **argv; 
{ 

static int val[ ] : { 0, i, 2, 3, 4 }; 
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Example 5-2. Toggle buttons used to Implement radio buttons (continued) 

toggle[ 0 ] = XtVaCreateManagedWidget ( 
"toggleO", /* arbitrary widget name */ 
toggleWidgetClass, /* widget class frcm Ccmnand.h */ 
box, /* parent widget* / 
XtNradioData, &val [ 0 ], 
XtNstate, True, 
NULL) ; /* terminate varargs list */ 
toggle[ 1 ] = XtVaCreateManagedWidget ( 
"togglel", /* arbitrary widget name */ 
toggleWidgetClass, /* widget class frcm Ccmnand.h */ 
box, /* parent widget*/ 
XtNradioData, &val [ 1 ], 
XtNradioGroup, toggle[ 0 ], 
NULL) ; /* terminate varargs list */ 
toggle[ 2 ] = XtVaCreateManagedWidget ( 
"toggle2", toggleWidgetClass, box, 
XtNradioData, &val [ 2 ], 
XtNradioGroup, toggle[ 1 ], 
NULL) ; 

toggle[ 3 ] = XtVaCreateManagedWidget ( 
"toggle3", toggleWidgetClass, box, 
XtNradioData, &val [ 3 ], 
XtNradioGroup, toggle[2 ], 
NULL) ; 

toggle[4] = XtVaCreateManagedWidget( 
"toggle4", toggleWidgetClass, box, 
XtNradioData, &val [ 4 ], 
XtNradioGroup, toggle[3 ], 
NULL) ; 

XtAddCallback(toggle[0 ], XtNcallback, Toggled, 0) ; 
XtAddCallback(toggle[l ], XtNcallback, Toggled, i) ; 
XtAddCallback(toggle[2 ], XtNcallback, Toggled, 2) ; 
XtAddCallback(toggle[3], XtNcallback, Toggled, 3); 
XtAddCallback(toggle[4], XtNcallback, Toggled, 4); 

Examp 5-3. App-deultsfileforxtogg 
*toggle0.1abel: Grilled 
*togglel.label: Boiled 
*toggle2.1abel: Fried 
*toggle3.1abel: Baked 
*toggle4.1abel: Incinerated 
*box.?.translations: #override\n\ 
<LeaveWindow>: unhighlight()\n\ 
<EnterWindow>: highlight(Always)\n\ 
<BtnlDown>,<BtnlUp>: set() notify() 
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5.2 Text Widgets 

The Text widget displays one or more lines of text. It can allow the user and program to edit 
the text, only append to the text, or only read the text. The widget optionally displays 
scrollbars. The user can search and optionally replace a specific string, and insert text read 
from a file. 

The insertion point in a Text widget is displayed as a caret between two characters in the file. 
The insertion point marks the location where any new characters will be added to the file. To 
avoid confusion the pointer (usually controlled by the mouse) is referred to as the pointer. 

5.2.1 

5.2.1.1 

User's View of the Text Widget 

The Text widget uses (by default) simplified Emacs keyboard editing commands. If an illegal 
operation is attempted, (such as deleting characters in a read-only text widget), the terminal 
bell is rung. In addition, the pointer may be used to cut and paste text. Multiple clicks (up to 
five) select progressively larger chunks of the text. 
Since all key and pointer bindings are set through translations, the user and the programmer 
can modify them by changing the Text widget's translations resource. 
The Text widget also supports search and replace and file insertion, as described in the next 
two sections. 

Search and Replace 

The Text widget provides a popup that can be used to search and replace a string within the 
current Text widget. The popup can be activated by typing either Control-r (search forward) 
or Control-s (search backward). The user can change the search direction at any time by 
clicking on the appropriate button in the popup. 

Within the search and replace popup, there are a few special key sequences: 

Carriage Return 
Tab 
Shift Carriage Return 
Control-q Tab 
Control-c 

Execute the action, and pop down the search widget. 
Execute the action, then move to the next field. 
Execute the action, then move to the next field. 
Enter a Tab into a text field. 
Pop down the search popup. 
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the dialog the pointer happens to be, and you need to allow Tab and Shift-Tab to move the 
keyboard focus forward and backward among the fields. To implement this so that type- 
ahead works properly, you need to use XAllowEvents() as described in Volume 
One, Xlib Programming Manual. Finally, you need some indication of which widget is the 
current keyboard focus, since the Text widget does not indicate it. All in all, it gets pretty 
involved. Anyway, this example is a start. For a more complete example, see the part of the 
source code for the Text widget that creates the search and replace dialog. 

Example 5-4. Code to make Text work for single-line text entry 

#include <Xll/Xaw/AsciiText.h> 

Widget addressl, address2, pshell, pressme, quit; 

/* 
* OK button 
*/ 
/*ARGSUSED*/ 
void DialogDone(w, client_data, call_data) 
Widget w; 
XtPointer client_data; /* cast to dialog */ 
XtPointer call_data; 
{ 
Widget dialog = (Widget) client_data; 

String stringl; 
String string2; 

XtPopdown(pshell); 

XtSetSensitive(pressme, TRUE); 
XtSetSensitive(quit, TRUE); 

XtVaGetValues(addressl, 
XtNstring, &stringl, 
NULL); 
XtVaGetValues(address2, 
XtNstring, &string2, 
NULL); 

printf('User's address is:\n%s\n%s\n', stringl, string2); 

/* Cancel button */ 
/ *ARGSUSED* / 
void DialogCancel(w, client_data, call_data) 
Widget w; 
XtPointer client_data, call_data; 
{ 
XtPopdown (pshell) ; 
XtSetSexitive (pressme, TRUE) ; 
XtSetSensitive (quit, TRUE) ; 
} 
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Example 5-4 Code to make Text work for single-line text entry (continued) 

/* For Return in First Text Field */ 
/*ARGSUSED* / 
void ReturnActionl(w, event, params, num_params) 
Widget w; 
XEvent *event; /* unused */ 
String *params; /* unused */ 
Cardinal *num_params; I* unused * I 
{ 
/* should move pointer and focus to next field */ 
} 

/* For Return in Second Text Field */ 
/ *ARGSUSED* / 
void ReturnAction2(w, event, params, nu_params) 
Widget w; 
XEvent *event; /* unused */ 
String *params; /* unused */ 
Cardinal *nu_params; I* unused *I 

String stringl; 
String string2; 

XtVaGetValues(addressl, 
XtNstring, &stringl, 
NULL); 
XtVaGetValues(address2, 
XtNstring, &string2, 
NULL); 

printf('User's address is:\n%s\n%s\n", stringl, string2); 

DialogCancel(w, NULL, NULL); 

main(argc, argv) 
int argc; 
char **argv; 
{ 
XtAppContext app_context; 
Widget box, topLevel, form, dialogDone, dialogCancel, label; 
XtTranslations TextFieldTranslations; 
static XtActionsRec actions[ ] = { 
{ "ReturnActionl', ReturnActionl }, 
{ "ReturnAction2", ReturnAction2 }, 
}; 

pshell = XtVaCreatePopupShell( 
"pshell", 
transientShellWidgetClass, 
topLevel, 
XtNallowShellResize, True, 
XtNirkDut, True, 
XtNtransientFor, topLevel, 
NULL); /* terminate varargs list */ 
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Example 5-4. Code to make Text work for single-line text entry (continued) 

form = XtVaCreateManagedWidget( 
"form", /* widget name */ 
formWidgetClass, /* widget class */ 
pshell, /* parent widget*/ 
NULL); /* terminate varargs list */ 

label : XtVaCreateManagedWidget( 
"label", /* widget name */ 
labelWidgetClass, /* widget class */ 
form, /* parent widget*/ 
XtNborderWidth, 0, 
NULL); /* terminate varargs list */ 

addressl = XtVaCreateManagedWidget( 
"addressl", 
asciiTextWidgetClass, 
form, 
XtNeditType, XawtextEdit, 
XtNresizable, True, 
XtNresize, XawtextResizeBoth, 
XtNfromVert, label, 
XtNright, XtChainRight, 
XtNleft, XtChainLeft, 
NULL); /* terminate varargs list */ 

address2 = XtVaCreateManagedWidget( 
"address2", 
asciiTextWidgetClass, 
form, 
XtNeditType, XawtextEdit, 
XtNresizable, True, 
XtNresize, XawtextResizeBoth, 
XtNfromVert, addressl, 
XtNright, XtChainRight, 
XtNleft, XtChainLeft, 
NULL); /* terminate varargs list */ 

dialogDone = XtVaCreateManagedWidget( 
"dialogDone", /* widget name */ 
commandWidgetClass, /* widget class */ 
form, /* parent widget*/ 
XtNfromVert, address2, 
NULL); /* terminate varargs list */ 

dialogCancel = XtVaCreateManagedWidget( 
"dialogCancel", /* widget name */ 
connandWidgetClass, /* widget class */ 
form, /* parent widget*/ 
XtNfromVert, address2, 
NULL); /* terminate varargs list */ 

XtAddCallback(dialogDone, XtNcallback, DialogDone, 0); 
XtAddCallback(dialogCancel, XtNcallback, DialogCancel, 0); 

TextFieldTranslations = XtParseTranslationTable 
("<Key>Return: ReturnActionl()\n\ 
Ctrl<Key>R: no-op(RingBell)\n\ 
Ctrl<Key>S: no-op(RingBell)\n"); 
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Example 5-4. Code to make Text work for single-line text entry (continued) 
XtOverrideTranslations (addressl, TextFieldTranslations) ; 
TextFieldTranslations = XtParseTranslationTable 
( "<Key>Return: ReturnAction2 ( ) \n\ 
Ctrl<Key>R: no-op (RingBell) \n\ 
Ctrl<Key>S: no-op (RingBell) \n" ) ; 
XtOverrideTranslations (address2, TextFieldTranslations) ; 
XtAppAddActions(app_context, actions, XtNumber(actions) ) ; 
XtReali zeWidget (topLevel) ; 

XtAppMainLoop (app_context) ; 

5.2.2.2 

The Editable Selection List 

The xrnh application uses the Text widget to list all the messages in the inbox, displaying the 
date, author, and subject of each one. The user can select messages but only in units of whole 
lines, and the selection is used to display the selected message or operate on a group of mes- 
sages, not to transfer text. This is accomplished primarily by changing the translations in the 
app-defaults file: 

Example 5-5. Changing Text widget translations for xmh 
*toc.baseTranslations: #override\n\ 
<Btn2Down>: select-start ( ) \n\ 
<Btn2Up>: select-end ( PRIMARY ) XmhViewNextMes sage ( ) \n\ 
Ctrl<Key>R: no-op (RingBell) \n\ 
Ctrl<Key>S: no-op (RingBell) \n 
Notice the use of the no-op action to disable the search-and-replace feature of the Text 
widget. The file insertion feature and all editing commands are already disabled because the 
resources are set so that this Text widget is read-only. 

5.2.3 

Customization 

The Text widget is made up of a number of pieces. The modularization of functionality is 
intended to ease customization. For most applications, the AsciiText widget will meet your 
needs. If more flexibility, special features, or extra functionality is needed, it can be added 
by implementing a new TextSource or TextSink, or by subclassing the Text widget. 
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6 

Inside a Widget 

This chapter describes the code inside a basic widget. Much of this code is 
common to all widgets. You can think of it as a framework that Xt uses to 
implement a widget's features. After reading this chapter, you should under- 
stand the procedure for creating your own widget around this framework. 

In This Chapter: 

Widget Source File Organization ........................................................ 150 
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6 
Inside a Widget 

This chapter reveals the framework of code common to all widgets. As an example, it 
describes the code for the BitmapEdit widget that was used in versions of the xbitmap appli- 
cations early in Chapter 4, An Example Application. Later examples in that chapter 
described how to implement the bitmap editor without a BitmapEdit widget. Therefore, you 
have already seen the code that is specific to this widget, and can concentrate on the frame- 
work and how to place widget-specific code within this framework. 
Some applications use only the standard user interface elements defined in the widget set. If 
you are writing an application like this, you have no need to write your own widgets, and no 
real need to understand the internals of widgets. However, many applications have at least 
one custom window which has features not supported by any existing widget. To implement 
such features, you can add to a Core widget from your application code or you can write your 
own widget. 
Placing specialized user-interface code into a widget has several advantages. For one, the 
widget becomes a self-contained module that can be modified and documented separately 
and used in other programs. Second, the code will take advantage of Xt's automatic dis- 
patching of events to widgets, and several other features that you can't use from the applica- 
tion. Finally, it is a general premise of Xt that application code should be separated as much 
as possible from user-interface code. 
It is important to remember that widget classes are never written from scratch. People 
always start from template files that contain the framework for a widget without the specific 
code, or even better, if possible, from an existing widget that has some similar characteristics. 
Therefore, you'll never have to type in the framework you're about to see. You'll only have 
to learn where to insert your code into it. The beauty of the widget framework is that the 
code within it is very modular--each module has a specific place and purpose. Once you 
understand the framework, you can locate these modules in existing code and use them as 
examples. Chapter 7, Basic Widget Methods, shows you how to write the most important 
modules within the framework. 
Writing your own widget is also known as subclassing a widget, because you always build 
off the features of some existing widget class. It is possible to subclass any existing widget, 
to add or modify features of the existing widget. However, to subclass a widget with existing 
features, you have to understand in detail how these features are implemented. Therefore, 
subclassing a complicated widget such as Text is very difficult. To implement a custom win- 
dow for an application, it is normally sufficient to subclass Core. 
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6.2 The Private Header File--BitmapEdiP.h 

Xt implements classes and instances with two structures, the class structure and the instance 
structure. By definition of C structures, the fields in both structures are fixed at compile time. 
Both of these structures are defined in the private include file for the class, in this case 
BitmapEdiP.h. 
There is only one copy of the class structure in the running application, which all instances 
share. But each instance has its own copy of the instance structure, whose fields are set by 
the resource database as the instance is created. Fields in the instance structure can also be 
set by XtVaSetValues ( ) or read by XtVaGetValues (). 
The class structure's fields contain pointers to methods and pieces of data that control how Xt 
handles instances of this class. 
The instance structure carries a complete widget state, including everything that can be dif- 
ferent between one instance and the next. For example, the instance structure of the Core 
class, which every widget inherits, has fields for x, y, width, and height values, which 
correspond to the size of the widget and its location relative to the top-left corner of its par- 
ent. These particular fields are public; they can be set from the resource database or with 
XtVaSetValues(), and their values can be read with XtVaGetValues (). Other 
instance structure fields are private, and are used only for convenience to make data globally 
available within the widget. 
Actually, the instance structure is not global in the normal C sense. When Xt invokes a 
method, it passes the method a pointer to the widget instance structure. Methods do their 
work by using the public fields and changing the private fields in this instance structure. For 
example, a method that draws in the window can get the window's dimensions directly from 
the widget instance structure. When action functions are called, they also are passed a 
pointer to the instance structure. Therefore, the fields inside the instance structure are avail- 
able just about everywhere in the widget code. 

6.2.1 

Parts and Records 

The organization of both class and instance structures is determined by the hierarchy of 
widget classes from which the current widget class is derived. For example, in the code for 
the BitmapEdit widget whose class hierarchy is shown in Figure 6-1, the class structure 
begins with the class fields defined by the Core class, followed by the class fields defined by 
BitmapEdit. 

Xt supplies three basic classes that are used as the basis for custom widgets, Core, Compos- 
ite, and Constraint.-]" Figure 6-1 also shows the relationship of these classes to each other. 
Core is the class upon which all widgets are based. It defines common characteristics of all 
widgets, such as their methods, and basic resources such as height and width. Even if your 
widget is unlike any existing widget, it will still inherit features from the Core widget. The 

Shell, the fourth Intrinsics-supplied widget class, is not usually subclassed by application or widget programmers. 
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Class Hierarchy 

Core 

' Constraint 

Figure 6-1. The class hierarchy of the BitmapEdit widget (with other classes shown dotted) 

class and instance structures of a subclass of Composite such as Box begin with the fields 
from Core, continue with fields from Composite, and end with the fields defined by Box. 
Composite and Constraint are subclasses of Core that have additional methods that allow 
them to manage children; they are described in Chapter 12, Geometry Management. This 
chapter concentrates on the features of the Core widget. 

Xt requires that you implement each class's new fields as a separate structure called a Part:, 
and then combine this Part: structure with each superclass's Part: structure in the complete 
structure called a Rec, or record. In real code, these structures are called 
widgetnameClassPart: and widgetnameClassRec for the class structure, and simply 
widgetnamePart: and widgetnameRec for the instance structure. 

The reason for this "structure within a structure" design is primarily to reduce the changes in 
the code of subclasses that would be required if changes were made to the superclass's struc- 
tures. As we will see later, only the portion of the .c file that initializes the class structure 
will need changing if a superclass class structure is changed. A second benefit of this design 
is that it reduces the amount of typing required to implement a new class. 

6.2.2 

Class Part and Class Record 

Let's make these ideas concrete by showing the class structure for BitmapEdit. The complete 
class structure is called Bit:mapEdit:ClassRec, and the partial structure is called 
Bit:mapEdit:ClassPart:. Their definitions from BitmapEdiP.h are shown below in 
Example 6-1. 

Example 6-1. BitmapEdiP.h: the class part and class record 
/* 
* BitmapEditP.h - Private definitions for BitmapEdit widget 
*/ 

/* protect against multiple including of this file */ 
#ifndef _ORABitmapEdit P_h 
#define _ORABitmapEdit P_h 

/* 
* This include not needed unless the .c file includes 
* IntrinsicP.h after this file. Anyway, it doesn't hurt. 
*/ 
#include <Xll/CoreP.h> 

/* 
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Example 6-1. BitmapEdiP.h: the class part and class record (conhnued) 
* This one is always needed! 
*/ 
# include "Bi tmapEdi t. h" 
/* New fields for the BitmapEdit widget class record */ 
typedef struct { 
int make_compiler_happy; /* need c field */ 
} BitmapEditClassPart; 
/* Full class record declaration */ 
typedef struct _BitmapEditClassRec { 
CoreClassPart core_class; 
BitmapEditClassPart bitmapEdit_class; 
} BitmapEditClassRec; 
Like most widget classes, BitmapEdit provides no new fields in the class part, but it needs 
one dummy member to make the C compiler happy. A class defines new class part fields to 
allow a subclass to choose to inherit a function or to replace it. Most classes don't define 
fields here because they don't plan to have subclasses. This fine point is described in Section 
12.4.5. 
You need to include the private header file of the superclass at the top of your private header 
file. The CorePart and CoreClassPart structures are defined in Core's private header 
file <Xll/CoreP.h>. The header files begin with an ifndef statement that allows the 
preprocessor to make sure that no header file is included twice. 
If the class structure contains a pointer to an extension structure, you can add to the class 
structure in later releases of your widget and maintain binary compatibility with subclasses. 
This feature is used in the basic Intrinsics classes Composite and Constraint, but is unlikely 
to be useful to you. However, when you do define an extension structure, you do so in the 
private header file. Extension structures are discussed in Section 14.13. 

6.2.3 

Instance Part and Instance Record 

The instance record is built exactly like the class structure: by defining new fields in a part 
structure, and then by combining the instance parts of all superclasses in the instance record. 
BitmapEditPart defines BitmapEdit's new widget instance fields, and the entire widget 
instance record is BitmapEditRec. These structures are defined in BitmapEdiP.h (along 
with the class structures just shown) and are shown in Example 6-2. We've included several 
likely instance variables, but none of those shown is an essential part of the widget structure. 

Example 6-2. BitmapEdiP.h: the instance part and instance record 
/* New fields for the BitmapEdit widget record */ 
typedef struct { 
/* resources */ 
Pixel foreground; 
XtCallbackList callback;/* application installed callback fns */ 
Dimension pixmap_width_in_cells; 
Dimension pixmap_height in cells; 
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Example 6-2. BitmapEdiP.h: the instance part and instance record (continued) 
int cell_size_in_pixels; 
int cur_x, cur_y; /* pstn of visible corner in big pixmap */ 
char *cell; /* for keeping track of array of bits */ 
Boolean showAll; /* whether bitmap should display 
entire bitmap */ 
/* private state */ 
Dimension pixmap_width_in_pixe i s; 
Dimension pixmap_height_in_pixe i s; 
pixmap big_picture; 
GC draw_gc; /* for drawing into pixmap */ 
GC undraw_gc; /* for undrawing into pixmap */ 
GC copy_go; /* for copying pixmap into window */ 
} BitmapEditPart; 
/* 
* Full instance record declaration 
*/ 
typedef struct _BitmapEditRec { 
CorePart core; 
BitmapEditPart bitmapEdit; 
} BitmapEditRec; 
#endif /* _ORABitmapEditP_h */ 
Unlike the class part, which generally defines no new fields, the instance part of a widget 
almost always defines new instance variables. These variables control all the configurable 
elements of the widget, and they hold the widget's state. 
Some of these instance variables are resources because they are listed in the resource list in 
the BitmapEdit.c file. (This resource list has exactly the same format as the resource list you 
saw in the application code in Section 3.5.2). These variables are known as public instance 
variables (because they are readable and writable from the application). By convention, the 
public instance variables are placed first in the instance part structure, and comments indicate 
which fields are public. When the application instantiates the widget, Xt sets the public fields 
based on the resource databases, the command line (the -xrm form), and the argument list 
passed to XtVaCreateManagedWidget (). Later on, the application may change these 
fields using XtVaSetValues (). 
The private instance structure fields (not listed in the widget's resource list) are either 
derived from resource values or they hold some aspect of the widget's state (such as whether 
it is highlighted). As in Example 6-2, graphics contexts (GCs) are always found here as pri- 
vate fields if the widget draws any graphics. Graphics contexts are needed for doing draw- 
ing, and are derived from public instance structure fields such as colors and fonts, because it 
is the GC that actually carries color and font information to the X server. GCs were intro- 
duced in Section 4.2.1. 
You may notice that the Part structures of the superclasses are referenced in the Bitmap- 
EditRec structure. As mentioned earlier, you get these by including the private include file 
of the imnediate superclass, which in turn includes the private include file of its own super- 
class, and so on. 
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Both the class and instance structures defined in BitmapEdiP.h are typedef templates; they 
do not allocate storage. Xt allocates storage for the instance record when the application 
calls XtVaCreateWidget ( ) or XtVaCreateManagedWidget ( ) to create the widget. 
The class record, on the other hand, is initialized statically (at compile time) in the .c file. 
The compiler makes sure that the definition of the class record (in BitmapEdiP.h) and the ini- 
tialization of the class record (in BitrnapEdit.c) use identical structures, since BitmapEdit.c 
includes BitmapEdiP.h. If a field is accidentally left out of the class structure in either file, 
the compiler will catch the problem (but if the same member is left out of both files, the prob- 
lem won't be caught and Xt will likely dump core). 
BitmapEdiP.h contains an extern reference to the class structure initialized in Bitmap- 
Edit.c. This reference is shown in Example 6-3. 

Example 6-3. BitmapEdiP.h: declaring the external class record 
extern BitmapEditClassRec bitmapEditClassRec; 
Because the private header file includes the public header file, there is no obvious reason for 
this extern declaration. But since all widget code seems to have it, we go along with the 
convention. The naming conventions for the various structure declarations in the private 
header file are important, and can be confusing. A table summarizing the conventions for 
types and variables in the widget implementation files is shown in Section 6.6 (after the con- 
tents of the .c and .h files are shown). 
That's all there is in the private header file! If you should need to refer back to the private 
header file for BitmapEdit, it is listed with the rest of the source for the widget in Appendix 
E, The xbitmap Application. 

6.3 The Widget Implementation File--BitmapEdit.c 

The central element of the .c file is the initialization of the class record. Remember that the 
typedef of the class record was declared in BitrnapEdiP.h, but the record is allocated and 
the actual values in each field are set in BitmapEdit.c. When Xt takes over control of the 
widgets after the application calls XtAppMa'i nr,oop (), it is the values in this class record 
that supply Xt with all the information it uses to manage widget instances. 

The organization of the .c file is quite simple. First, it defines everything that will be placed 
into the class record, and then initializes the class record, setting fields using these defini- 
tions. The major things that need defining are the functions that implement each method, the 
resource list, the translation table, and the actions table. It would be logical to define these 
four things at the beginning of the source file, and then put the class record last. This is 
almost the case, except that by convention the methods and actions are declared at the top of 
the source file and then defined at the end after the class record initialization. This actually 
makes the widget code clearer because the method declarations provide a complete list of the 
methods that will be defined later in the file, and the class record remains near the top of the 
file where it's easier to find. (Not all the methods have to be defined by a class, because some 
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Example 6-5. BitmapEdit's resource list (continued) 
sizeof (String), 
offset (bitmapEdit. cell), 
XtRInmediate, 
(XtPointer) 0 
}, 
{ 
XtNshowEnt i reB i tmap, 
XtCShowEntireBitmap, 
XtRBoolean, 
sizeof (Boolean), 
offset (bitmapEdit. showAl i), 
Xtate, 
(XtPointer) True 
}, 

}; 

The details of each field in a resource list entry is presented in Chapter 10, Resource Man- 
agement and Type Com'ersion. 
As mentioned earlier, a widget class inherits all the resources defined in the resource lists of 
its superclasses. If a resource is given the same name as a superclass resource, it overrides 
the superclass resource. One reason to create a new resource with the same name as a super- 
class resource is to give it a new, subclass-specific default value. Another reason is to pro- 
vide further processing on a resource value. 
When defining a resource list, use constants defined in <Xll/StringDefs.h> whenever pos- 
sible. However, any constant unique to this widget class can be defined in the public include 
file, as is described in the next section. 
Table 6-1 summarizes the conventions for the constants used in the resource list. 

Table 6-1. Resource List Constant Conventions 

Prefix 

XtN 
XtC 
XtR 

First word capitalization 

Lower 
Upper 
Upper 

Description 

Resource name 
Resource class 
Representation type 

The representation type of a resource is a string that represents the type in which the widget 
stores the resource value. Xt constants and functions of all types use uppercase letters when- 
ever a word break might otherwise be called for. Two examples of resource names following 
this convention are XtNborderColor and XtNmappedWhenManaged. 

Example 6-6 shows how the resource list is entered into the class structure. You'll see this 
again in Section 6.3.5 where we show the entire class record and describe how to initialize it. 
The names of the fields in the class structure are shown in the comments at right. 
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Examp 6-6. Seing eresourcelist e class structure 
BitmapEditClassRec bitmapEditClassRec = { 
{ /* Core class part */ 

resources, 
XtNumber(resources), 

/* resources */ 
/* resource_count */ 

e 
{ /* BitmapEdit class part */ 
0, /* durm_field */ 
} 
}; 
Note that a widget or an application can get the resource list for a class using XtGet- 
ResourceList (), which returns a pointer to a resource list of the same form as shown 
above. This function isn't needed in most applications or widgets. 

6.3.3 

The Translation Table and Actions Table 

You may recall that the translation table maps event sequences into string action names, and 
the action table then maps string action names into actual action functions. This is done in 
two steps so that the translation table is a single string that can be specified in the resource 
databases (since resource databases are always composed entirely of strings). The action 
table is not configurable through the resource database, but it can be added to the application 
or with XtAppAddAct ion (s). 
Like the resource list, the default translation table and the actions table have to be defined 
before the class record can be initialized. They determine which events this widget will 
respond to, and which functions defined in this source file will be triggered by those events. 
The translation table is a resource defined by the Core class. It is a strange resource in sev- 
eral ways. It has no default value in the resource list. Instead, the default translation table is 
initialized into the class structure. Translations are not inherited like other resources--you 
do not get the sum of all the translation tables registered by the superclasses. Rather, the 
translation table you specify in the class structure is the only one (in the code) that matters. 
However, you can choose to use the immediate superclass's translation table instead of defin- 
ing one, in which case you initialize the translation table field in the class structure to be Xt- 
InheritTranslations. 
Each widget has its own action list, and if the application registers an action list, it is kept as 
a separate list. When an event combination occurs in a widget, Xt translates the event combi- 
nation into an action string and searches that widget's action list. If the action string is found 
in the widget's action list, the search stops and that action function is called. If the action 
string is not found in the widget's action list, then the application's action list is searched. If 
neither list contains the appropriate action string, Xt prints a diagnostic warning. If the appli- 
cation and the widget both define the same action string in the actions table, the application's 
function mapped to that string will never be called. Two widget classes, however, may have 
the same action function name, and they will not conflict. 
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6.3.5 Initializing the Class Record 

6.3.5.1 

We've already shown you how to create the resource list, the translation table, and the 
actions table, and set into the class structure. A major part of the work is done. Now we just 
need to insert the method names we declared earlier into the class record, and set a few of the 
miscellaneous data fields. 

As we saw in the discussion of the private header file, the BitmapEdit class record includes 
class parts for BitmapEdit itself and for each superclass of BitmapEdit, in this case Core. To 
initialize the class record, each class part has to be initialized field by field. Fortunately this 
is easy because the majority of the fields are always initialized to the same values. 

The Core Class Part 

Since all widget classes are subclasses of Core, all need to initialize the Core class part. 
Example 6-10 shows the core part initialized as needed by the BitmapEdit widget. The 
actual name of each field is shown in the comment at left. Each field will be discussed after 
the example. 

Example 6-10. BitmapEdit.c: initialization of Core class record 
BitmapEditClassRec bitmapEditClassRec : { 

{ /* core_class fields */ 
/* superclass */ (WidgetClass) &coreClassRec, 
/* class_name */ "BitmapEdit", 
/* widget_size */ sizeof(BitmapEditRec), 
/* class_initialize */ NULL, 
/* class_part_initialize */ NULL, 
/* class_inited */ False, 
/* initialize */ Initialize, 
/* initialize_hook */ NULL, 
/* realize */ XtInheritRealize, 
/* actions */ actions, 
/* nunl_actions */ XtNumber(actions), 
/* resources */ resources, 
/* nu_resources */ XtNumber(resources), 
/* xrm_class */ NULLQUARK, 
/* compress_motion */ True, 
/* compress_exposure */ XtExposeCompressMultiple, 
/* compress_enterleave */ True, 
/* visible_interest */ False, 
/* destroy */ Destroy, 
/* resize */ Resize, 
/* expose */ Redisplay, 
/* set_values */ SetValues, 
/* set_values_hook */ NULL, 
/* set_values_almost */ XtInheritSetValuesAlmost, 
/* get_values_hook */ NULL, 
/* accept_focus */ NULL, 
/* version */ XtVersion, 
/* callback_private */ NULL, 
/* t_table */ defaultTranslations, 
/* query_geometry */ QueryGometry, 
/* display_accelerator */ XtInheritDisplayAccelerator, 
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Backing Store Provides hints about when a window's contents should be preserved by the 
server even when the window is obscured or unmapped. This is useful for 
widgets that are very time-consuming to redraw. Not all servers are cap- 
able of maintaining a backing store. Check the value returned from the 
Xlib DoesBackingStore ( ) macro to determine whether this feature is 
supported on a particular screen on your server. 
Saving Under Provides hints about whether or not the screen area beneath a window 
should be saved while a window such as a pop-up menu is in place, to save 
obscured windows from having to redraw themselves when the popup is 
removed. Not all servers can save under windows. You can find out 
whether this feature is supported on a particular screen with the Xlib 
DoesSaveUnders ( ) macro. 
Colormap Determines which virtual colormap should be used for this window. If 
your widget requires a lot of specific colors--for example, to draw a shad- 
ed image, it may need to create its own virtual colormap. In that case, it 
would set this attribute to the ID of the created colormap. For more infor- 
mation, see Chapter 7, Color, in Volume One, Xlib Programming Manual. 
Cursor Determines which cursor should be displayed when the pointer is in this 
window. You must create this cursor before setting this attribute. This can 
be done with a standard type convener, as described in Chapter 14, Mis- 
cellaneous Toolkit Programming Techniques. 
It may clarify the picture to describe the features that window attributes do not affect. Set- 
ting the window attributes does not determine a window's parent, depth, or visual. These are 
all set when a window is created, and are permanent. The window attributes are also not 
used for setting the size, position, or border width of a widget. These are set using Xt:Set:- 
Values ( ). Window attributes do not determine how graphics requests are interpreted; this 
is the job of the graphics context (GC). 
Note that some of the window attributes are not listed here because they should not be set di- 
rectly by widgets, in the realize method or anywhere else. These include the 
event_mask, which controls which events are sent to this widget. Xt itself sets this win- 
dow attribute based on the translation table. Another is override_redirect:, which is 
handled by the Shell widget. 
You could write a realizo method that set your desired attributes and then called 
CreateWindow (). But this is slightly wasteful, since Core already has a realize meth- 
od that creates a window and you can take advantage of it. This is the second inheritance 
scheme used for self-contained fields. You define your own realize method just as if you 
were going to write it from scratch, but then you call the superclass's realize method di- 
rectly, as shown in Example 6-13. 
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instance structure, this pointer must be cast to type BitmapEditWidget. The easiest 
way to do this is to declare the argument of the method as type BitmapEditWidget 
(the other way is to cast in an assignment). 

If your resource list uses XtN, XtC, or XtR constants not defined in <XI l/StringDefs.h>, you 
must define them in the public include file. The definitions should have only a single space 
between the definition and the value, with no trailing comment or space. This reduces the 
possibility of compiler warnings from similar but not identical definitions in multiple classes. 
If you want, you can use a different convention for the symbol names, to distinguish your 
constants from those defined by Xt. For example, you could start them all with Xo. 
If a widget offers any public functions, they would be declared extern here (and actually 
defined in the .c file). Public functions allow the application to read or change certain private 
data in certain more restricted or more convenient ways than is possible with resources. For 
example, the BitmapEdit widget provides the public function BitmapEditGetArray that 
applications can call to get the array of bits currently stored as private data in the widget. 
(This array is an attribute readable with XtGetValues ( ), but using this function is more 
convenient because it also returns the dimensions of the array.) 
Example 6-14 shows BitmapEdit's public header file. 

Example 6-14. BitmapEdit.h: complete public header file 
#ifndef _ORABitmapEdit_h 
#define _ORABitmapEdit_h 
/* BitmapEdit Widget public include file */ 
/* 
* Include superclass public header file. 
*/ 
#include <Xl i/Core, h> 
/* 
* This public structure is used as call_data to the callback. 
* It passes the x, y position of the cell toggled (in units of 
* cells, not plxels) and a mode flag that indicates whether the 
* cell was turned on (i) or off (0). 
*/ 
typedef struct { 
int mode; 
int newx; 
int newy; 
} BitmapEditPoint Info; 

#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 

#define 
#define 
#define 

XtNtoggleCallback "toggleCallback" 
XtNcellSizeInPixels "cellSizeInPixels" 
XtNpixmapWidthInCells "pixmapWidthInCells" 
XtNpixmapHeightInCells "pixmapHeightInCells" 
XtNcurX "curX" 
XtaNcuY "cuY" 
XtNcellArray "cellArray" 
XtNshowEntireBitmap "showEntireBitmap" 
XtCToggleCallback "ToggleCallback" 
XtCCellSizeInPixels "CellSizeInPixels" 
XtCPixmapWidthInCells "PixmapWidthInCells" 
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6.6 Summary of Conventions 

The naming conventions for the various structure declarations in the widget source files can 
be confusing. Table 6-3 summarizes these conventions, using the BitmapEdit widget as an 
example, and describes where each type is used. This table is just to help you read the code. 
If you create a new class starting from an existing class, and globally change the names as 
described above, all of the definitions and references listed here will already be done for you. 

Table 6-3. Summary of Xt Structure Name Conventions 

Structure Name 

BitmapEditClassPart 

BitmapEditClassRec 

bitmapEditClassRec 

BitmapEditPart 

BitmapEditRec 

_BitmapEditRec 

_BitmapEditClassRec 

BitmapEditWidget 

BitmapEditWidgetClass 

bitmapEditWidgetClass 

Description 

Partial class structure typedef (usually dummy field only) used for de- 
fining BitmapEditCqassRec in P.h file. 
Complete class structure typedef, declared extern in P.h file, used 
for initializing class structure in .c file. 
Name of complete class structure allocated in .c file, declared ex- 
tern in P.h file, allocated in .c file, used as superclass in class record 
initialization of subclasses of this widget (.c file). 
Partial instance structure typedef, used for defining BitmapEdit- 
Rec in P.h file. 

Complete instance structure typedef, also used to initialize widg- 
et_size field of class record in .c file. 
Type of BitmapEditRec, used for defining Bitmap- 
EditWidget pointer in .h file. 
Type of BitmapEditClassRec, used for defining Bitma- 
pEditWidgetClass pointer in .h file. 
Pointer to BitmapEditRec (complete instance structure), used to 
reference instance structure fields in .c file (passed as argument to 
methods). 
Pointer to _BitmapEditClassRec, used to cast bitmap- 
EditClassRec for superclass in class record initialization of sub- 
classes of this widget (.c file). 
Of type WidgetClass, address of bitmapEditClassRec, used 
in XtVaCreateManagedWidget () calls to identify class to be 
created. 
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7 

Basic Widget Methods 

This chapter describes the initialize, expose, set_values, resize, 
query_geometry, and destroy methods. It explains when Xt calls each 
method, and describes in detail what should be in each of these methods. 
Among other things, these methods prepare for and do the drawing of graph- 
ics that appear in a widget. This chapter describes what the Toolkit adds to 
the graphics model provided by Xlib, but does not describe in detail how to 
draw using Xlib; this topic is described in Chapters 5, 6 and 7 of Volume 
One, Xlib Programming Manual This chapter also describes how to write 
action routines that work in the widget framework. 

In This Chapter: 

The X Graphics Model Inside Widgets ............................................... 180 
The initialize Method .......................................................................... 181 
Creating GCs ................................................................................. 183 
The expose Method ........................................................................... 185 
The set values Method ...................................................................... 189 
-- 
The resize Method ............................................................................. 191 
The query_geometry Method ............................................................. 194 
The destroy Method ........................................................................... 197 
Actions in the Widget Framework ....................................................... 198 



draw in a widget, and it's easier to add processing of user input as described in 
Chapter 8, Events, Translations, and Accelerators. 

7.1 

The X Graphics Model Inside Widgets 

Section 4.4.1 described the X graphics model and how drawing from the application is 
accomplished. In summary, the process consisted of creating GCs and then drawing from a 
function that Xt calls on receipt of Expose events. Drawing from inside a widget follows 
the same general procedure, but the code is organized differently. 
Inside a widget, you normally create GCs with the Xt routine XtGetGC() or Xt- 
AllocateGC instead of the Xlib routine XCreateGC (). XtGetGC ( ) is similar to the 
Xlib routine except that it arranges for the sharing of GCs among widgets within an applica- 
tion. This is important because each GC has some overhead and servers can achieve better 
performance when handling fewer GCs. Because Xt applications often have many instances 
of the same widget class, each needing the same GC characteristics (unless the user specifies 
a different color for each one), Xt arranges for them to share GCs when possible. The draw- 
back with XtGetGC () is that no instance is allowed to modify the returned GC, because 
some other widget instance may be depending on it. XtAllocateGC() supports more 
flexible sharing. You specify which fields your widget wants the ability to change, and those 
that it doesn't care about, so that some other widget may get the same GC if it only needs to 
change the latter fields. 
Xt organizes GC creation and drawing into separate methods. Setting initial values for the 
GC and creating the GC is done in the initialize method, and actual drawing is done in 
the expose method. This makes it very easy to find this code in existing widgets and 
straightforward to write this code for new widgets. 
Since Xt allows resources to be changed during program execution by calling XtVaSet- 
Values ( ), the widget code must be prepared to change the GC at any time if the GC com- 
ponents depend on resource values. The set. values method calculates the new values 
based on resource changes and updates the appropriate GCs. 
The next six major sections discuss the code needed to implement the initialize, 
expose, set_values, resize, query_geometry, and destroy methods. 
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7.2 The initialize Method 

As described in Section 6.3.5.2, the initialize method has basically one function: it sets 
instance structure members (also called instance variables).% This job has two pans: setting 
the initial values of private instance variables, and checking to make sure that the values of 
the public instance variables are valid (since they are user configurable). Since the ini- 
tialize method is upward chained (defined in Section 6.3.5.2), the method for this class 
needs to initialize only the fields present in the instance pan structure for this class. The 
exceptions are width and height. Even though they are instance variables of Core, they 
need to be checked by the subclass, because only this class knows its desired initial size. 

Example 7-1 shows the init ial i z e method from BitmapEdit. 

Example 7-1. The initialize method 
/* ARGSUSED */ 
static void 
Initialize(treq, tnew, args, nunl_args) 
Widget treq, tnew; 
ArgList args; 
Cardinal *nunl_args; 
{ 
BitmapEditWidget new = (BitmapEditWidget) tnew; 
new->bitmapEdit.cur_x = 0; 
new->bitmapEdit.cur_y = 0; 
/* 
* Check instance values set by resources that may be invalid. 
*/ 

if ( (new->bitmapEdit.pixmap_width_in_cells < i) I I 
(new->bitmapEdit .pinap_height_in_cells < i) ) 
XtWarning ( "BitmapEdit: pinapWidth and/or pixmapHeight\ 
is too small (using i0 x i0)."); 
new->bitmapEdit .pixmap_width_in_cells = i0; 
new->bitmapEdit.pixmap_height_ir_cells = i0; 
} 

if (new->bitmapEdit.cell_size_inpixels < 5) { 
XtWarning("BitmapEdit: cellSize is too small (using 5) 
new->bitmapEdit .cell_size_inpixels = 5; 
} 

if ( (new->bitmapEdit .cur_x < 0) I I 
(new->bitmapEdit.cur_y < 0) ) { 
XtWarning("BitmapEdit: cur_x and cur_y must be\ 
non-negative (using 0, 0).'); 
new->bitmapEdit.cur_x = 0; 
new->bitmapEdit.cur_y = 0; 
} 

/* 
* Allocate memory to store array of cells in bitmap, if not 

#As described in Chapter 12, Geometry. Management, the initialize method can also be used for creating child 
widgets, to build a compound widget. This is a way of getting around Xt's geometry management scheme, and is not 
frequently done. 

Basic Widget Methods 181 



As you should recall from Chapter 6, Inside a Widget, all the variables set in initialize 
are declared in the BitmapEditPart instance structure in the private header file. 
Note that most of the arguments of initialize are rarely used. When initialize is 
called, the request argument is an instance structure containing the same values as new. 
But as new is changed, request provides a sometimes useful record of the resource set- 
tings originally made by the user. The args and num_args arguments contain the resource 
settings provided in the call to XtVaCreateManagedWidget (). These are sometimes 
useful in distinguishing between settings made by the application (args) from settings made 
by the user (which already appear in new and request). The code in the initial- 
i ze._hook method, described in Chapter 10, Resource Management and Type Com'ersion, 
can optionally be placed in the initialize method. 

7.2.1 

Creating GCs 

In any widget that does drawing, some of the private instance variables will hold the IDs of 
GCs created in the initialize method. These variables will be read when the GCs are 
needed in the expose method, and will be reset if necessary in the set_values method. 
Example 7-1 called separate routines, GetDrawGC, GetUndrawGC, and GetCopyGC to 
create the GCs. Example 7-2 shows these routines. 

A program prepares for creating a GC by setting the desired characteristics of the GC into 
members of a large structure called XGCValues (defined by Xiib), and specifying which 
members of XGCValues it has provided by setting a bitmask. This bitmask is made by 
ORing the GC mask symbols defined in <Xll/X.h>. Each bitmask symbol represents a mem- 
ber of the XGCValues structure. Every GC field has a default value, so only those values 
that differ from the default need to be set. The default GC values are discussed in Volume 
One, Xlib Programming Manual. 

Widget code normally creates a GC with the XtGetGC() call, not the Xlib analogue 
XCreateGC ( ). XtGetGC ( ) keeps track of requests to get GCs by all the widgets in an 
application, and creates new server GCs only when a widget requests a GC with different 
values. In other words, after the first widget creates a GC with XtGetGC ( ), any subsequent 
widget that calls XtGetGC ( ) to create a GC with the same values will get the same GC, not 
a new one. Using this client-side caching also reduces the number of requests to the server. 

Xlib provides XChangeGC ( ) to change the values in an existing GC. Xt provides no analo- 
gue. Because of the sharing of GCs allocated with XtGetGC ( ), you must treat them as 
read-only. If you don't, you may confuse or break other widgets. In cases where your widget 
creates a GC that needs changing in such a way that it is impractical to create a new GC each 
time, it may be appropriate to use the Xlib call XCreateGC ( ) instead of the Xt call Xt- 
GetGC (). 

BitmapEdit must use XCreateGC () for two of its three GCs because these GCs are for 
drawing into pixmaps of depth 1, while XtGetGC ( ) always creates GCs for drawing into 
windows or pixmaps of the default depth of the screen. In other words, XtGetGC ( ) would 
work on a monochrome screen, but not on color. However, this is an unusual situation. Most 
widgets can use XtGetGC ( ) exclusively. 
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XtNforeground resource defined by BitmapEdit. The background pixel value is derived 
from a resource of the Core widget. (Core defines a background resource but no foreground.) 
On the other hand, the line_style member of XGCValues is set to LineOnOffDash 
regardless of resource settings. In general, you hardcode the GC components that you don't 
want to be user customizable. (All these instance variables are defined in the 
yourwidgetPart structure defined in yourwidgetP.h.) 

Certain GC parameters are traditionally handled as resources rather than being hardcoded. 
Colors and fonts are the most basic examples. In the X Window System you can't use a color 
until you allocate a pixel value for it, and you can't use a font until you load it. The code that 
processes resources called by XtAppInitialize ( ) automatically allocates and loads the 
colors and fonts specified as resources, and sets the instance variables to the right representa- 
tion type as specified in the resource table. Therefore, it is actually easier to provide user 
customizability than to convert values to the representation types required to hardcode them. 

How the resource conversion process works is described in more detail in 
Chapter 10, Resource Management and Type Conversion. To decide which GC settings you 
need for your application, see Chapter 5, The Graphics Context, in Volume One, Xlib Pro- 
gramming Manual. 

7.3 

The expose Method 

The expose method is responsible for initially drawing into a widget's window and for 
redrawing the window every time a part of the window becomes exposed. This redrawing is 
necessary because the X server does not maintain the contents of windows when they are 
obscured. When a window becomes visible again, it must be redrawn. 
The expose method usually needs to modify its drawing based on the geometry of the win- 
dow and other instance variables set in other methods. For example, the Label widget will 
left-justify, center, or right-justify its text according to the XtNalignment resource, and 
the actual position to draw the text depends on the widget's current size. The Label widget 
has an instance structure field called alignment, which is set initially in the initialize 
method, and is read in Label's expose method. 
Another factor to consider when writing the expose method is that many widgets also draw 
from action routines, in response to user events. For example, BitmapEdit toggles bitmap 
cells in action routines. The expose method must be capable of redrawing the current state 
of the widget at any time. This means that action routines usually set instance variables 
when they draw so that the expose method can read these instance variables and draw the 
right thing. 
Most widgets keep track of what they draw in some form of arrays or display lists. When 
they need to redraw, they simply replay the saved drawing commands in the original order to 
redraw the window. For example, BitmapEdit keeps track of the state of each bitmap cell in 
a character array. It could easily traverse this array and redraw each cell that is set in the 
array. 
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However, BitmapEdit does not use this strategy. In order to improve its scrolling perfor- 
mance, the expose method copies an off-screen pixmap into the window whenever 
redisplay is required. The actions draw into this off-screen pixmap (in addition to updating 
the character array), and then call the expose method directly to have the correct portion of 
the pixmap copied to the window. 
The expose method is passed an event that contains the bounding box of the area exposed. 
To achieve maximum performance it copies only this area from the pixmap to the window. 
The BitmapEdit actions take advantage of this, too. They manufacture an artificial event 
containing the bounding box of the cell to be toggled, and pass it when they call expose. 
This causes the expose method to copy that one cell that was just updated to the window. 
Example 7-3 shows the expose method from the BitmapEdit widget. 
Example 7-3. The expose method 
I* ARGSUSED * I 
static void 
Redisplay(w, event, region) 
Widget cw; 
XExposeEvent *event; 
Region region; 
{ 
BitmapEditWidget cw = (BitmapEditWidget) w; 
register int x, y; 
unsigned int width, height; 
if (!XtIsRealized(cw)) 
return; 
if (event) { /* called from btn-event */ 
x = event->x; 
y = event->y; 
width = event->width; 
height = event->height; 
} 
else {/* called because of expose */ 
x= 0; 
y=0; 
width = cw->bitmapEdit.pixmap_width_in_pixels; 
height = cw->bitmapEdit.pixmap_height_in_pixels; 
} 
if (DefaultDepthOfScreen(XtScreen(cw)) == i) 
XCopyArea (XtDisplay (cw), cw->bitmapEdit .big_picture, 
XtWindow(cw), cw->bitmapEdit.copy_gc, x + 
cw->bitmapEdit.cur_x, y + cw->bitmapEdit.cur__v, 
width, height, x, y); 
else 
XCopyPlane (XtDisplay (cw), cw->bitmapEdit .big_picture, 
XtWindow(cw), cw->bitmapEdit.copy_gc, x + 
cw->bitmapEdit, cur_x, y + cw->bitmapEdit, cur_y, 
width, height, x, y, i); 
} 
Note that the expose method first checks to see that the widget is realized using Xt- 
IsRealized(). This is a precaution against the unlikely event that an instance of this 
widget is suddenly destroyed or unrealized by an application while Expose events are still 

186 X Toolkit Intrinsics Programming Manual, Athena Edition 



pending. If this did happen, drawing on the nonexistent window would cause an X Protocol 
error. 
Next, BitmapEdit's expose method sets the rectangle it will redraw based on the event 
passed in by Xt. We also call this method directly from the action that processes button 
presses. That action routine creates a pseudo-event to pass to expose to describe the area to 
be drawn. 
If the compress_exposure field of the class structure is initialized to XtExpose- 
CompressNultiple (or one of a few other constants, described in Chapter 9, More Input 
Techniques), as it is in BitmapEdit, Xt automatically merges the multiple Expose events 
that may occur because of a single user action into one Expose event. In this case, the 
Expose event contains the bounding box of the areas exposed. BitmapEdit redraws every- 
thing in this bounding box. For widgets that are very time-consuming to redraw, you might 
want to use the third argument of the expose method, which is a region. The Region type 
is opaquely defined by Xlib (internally a linked list of rectangles). The Region passed into 
expose describes the union of all the areas exposed by a user action. You can use this 
region to clip output to the exposed region, and possibly calculate which drawing primitives 
affect this area. Xlib provides region mathematics routines (such as XRect:InRegion ( ) ) 
to compare the regions in which your widget needs to draw with the region needing redraw- 
ing. If certain areas do not require redrawing, you can skip the code that redraws them, 
thereby saving valuable time. However, if this calculation is complicated, its cost/benefit 
ratio should be examined. Consider the arrangement of windows shown in Figure 7-1. 
Window 1 and Window 3 are other applications, and Widget 2 is an application consisting 
solely of our widget. 
Initially, Window 3 is on top, Window 1 is behind it, and Widget 2 is hidden completely 
behind Window 1. When Window 1 is lowered, Widget 2 becomes visible, except where it is 
still overlapped by Window 3. The newly-exposed area can be described by two rectangles; 
A and B. If compress_exposure is False, Widget 2's expose method will be called 
twice and passed an Expose event first describing Rectangle A, then Rectangle B. But if 
compress_exposure is True, Widget 2's expose method will be called just once, 
passed an Expose event describing the bounding box of all the original Expose events 
(which would be the entire widget in this case), and passed a Region which is the union of 
the rectangles described by all of the Expose events. The region argument of the 
expose method is unused unless compress_exposure is True. Each of these expo- 
sure-handling techniques may be the best for certain widgets. For a widget like BitmapEdit, 
any of the three methods will work, but the bounding box method is the most efficient and 
convenient. For a complete description of Expose event handling strategies, see Chapter 8, 
Events, in Volume One, Xlib Programming Manual. 
The remainder of BitmapEdit's expose method shown in Example 7-3 consists of a single 
Xlib call to copy from a pixmap into the widget's window. As described in Chapter 4, 
An Example Application, BitmapEdit makes a large pixmap that is one plane deep and draws 
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Figure 7-1. compress_exposure: 2 rectangles if XtExposeNoCompress; bounding box and 
region if XtExposeCompressSeries or XtExposeCompressMultiple 

the current bitmap into it. When needed in the expose method, this pixmap just has to be 
copied into the window. This approach was chosen for its simplicity. When scrollbars are 
added, the widget is able to pan around in the large bitmap quickly and efficiently. Note that 
one of two Xlib routines is called based on the depth of the screen. This is because 
XCopyArea () is slightly more efficient than XCopyPlane () and should be used when 
running on a monochrome screen. 

Note that instance variables are used for the arguments of the Xlib routines in Example 7-3. 
Don't worry about exactly what each Xlib routine does or the meaning of each argument. 
See the reference page for each routine in Volume Two, Xlib Reference Manual, when you 
need to call them in your code. 

See Chapters 5, 6, and 7 in Volume One, Xlib Programming Manual, for more information 
on the GC, drawing graphics, and color, respectively. There is another example of an 
expose method on the expose reference page in Section 4 of Volume Five, X Toolkit 
Intrinsics Reference Manual. 
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7.4 The set values Method 

When the application calls XtVaSetValues ( ) (or XtSetValues ( ) ) to change widget 
resources during run time, Xt calls the set_values method. The set_values method is 
where a widget responds to changes in its public instance variables. It should validate the 
values of the public variables, and recalculate any private variables that depend on public 
variables that have changed. 
Example 7-4 shows the set_values method for BitmapEdit. 

Example 7-4. The set_values method 
/* ARGSUSED */ 
static Boolean 
SetValues(current, request, super, args, num_args) 
Widget current, request, super; 
ArgList args; 
Cardinal *numargs; 
{ 
BitmapEditWidget curcw = (BitmapEditWidget) current; 
BitmapEditWidget newcw = (BitmapEditWidget) super; 
Boolean do_redisplay = False; 

if (curcw->bitmapEdit.foreground l= newcw->bitmapEdit.foreground) { 
XtReleaseGC (curcw, curcw->bitmapEdit.copy_gc) ; 
GetCopyGC (newcw) ; 
do_redisplay = True; 
} 

if ( (curcw->bitmapEdit.cur_x l= newcw->bitmapEdit.cur_x) II 
(curcw->bitmapEdit.cur_y != newcw->bitmapEdit.cur_y) ) 
do_redisplay = True; 

if (curcw->bitmapEdit.cell_size in pixels := 
newcw->bitmapEdit.cell_size in 9ixels) { 
ChangeCellSize (curcw, newcw->bitmapEdit, cell_size_in_pixels) ; 
do_redisplay = True; 
} 

if (curcw->bitmapEdit .pixmap_width_in_cells ! = 
newcw- >bitmapEdit. pixmap_width_in_ce i i s ) { 
newcw- >bitmapEdit. pixmap_width_in_cel i s = 
curcw->bitmapEdit.pinap_width in cells; 
XtWarning ( "BitmapEdit: pixmap_width_in_cells cannot\ 
be set by XtSetValues.\n"); 
} 

if (curcw->bitmapEdit .pinap_height_in_cells ! = 
newcw->bitmapEdit.pixmap_height in cells) { 
newcw->bitmapEdit.pinap_height in cells = 
curcw- >b i tmapEdi t. p inap_he i ght_in_ce i i s; 
XtWarning( "BitmapEdit : pixmap_height in cells cannot\ 
be set by XtSetValues. \n"); 
} 

return do_redisplay; 
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Because of the two-phase resize strategy used by BitmapEdit, and because BitmapEdit uses a 
pixmap in its repaint strategy, this resize method is more complicated than most. When 
the widget is resized larger that necessary to show the entire bitmap in the current 
cell_size, it destroys the current pixmap and creates a new one. Since this should not 
happen very often and because resizing does not require extremely fast response, the time it 
takes to recreate the pixmap and draw into it is acceptable. 
One difficulty in writing the resize method is that you do not have access to the old size or 
position of the window. The widget instance structure passed in has already been updated 
with the current size and position. If you need the old information, you can cache the old 
size in an instance part field, set first in the initialize method, and again at the end of 
the resize method. 
It is also important to note that the resi ze method is not aliowed to request that the parent 
resize the widget again to get a better size. (How to suggest properly to the parent that your 
widget be resized is described in Chapter 12, Geometry Management.) 

7.6 The query_geometry Method 

When your widget is used in an application, its parent widget will be a composite or con- 
straint widget that manages its size and position. Parent widgets need to know the preferred 
size of a widget so they can make good decisions about the size of each child. The 
query_georaetry method is called when the parent is about to make a size change to 
some of its children but is not yet sure which ones and by how much. (How geometry man- 
agement works is described in Chapter 12, Geornetry Management. For now, we are concen- 
trating on what you need to do to write a simple widget.) 

If your widget specifies NULL in the class structure for the query_geometry method, the 
parent will be told that your widget's current geometry is its preferred geometry. This is 
often wrong information. For example, if your widget has already been resized to be one- 
pixel-by-one-pixel because the user has resized an application to be very small, the parent 
would receive the message that your widget prefers to be that small. When the application is 
resized to be larger again, the parent will have no information on which to base its resizing 
decisions. Even if your widget has no particular preference for size, it is a good idea to spec- 
ify the widget's default size in query_geometry. Then, at least, the parent has a ballpark 
figure for typical sizes for your widget. The parent could at least find out that BitmapEdit is 
intended to be larger than a Label widget. 
The query_geometry method is passed pointers to two copies of the XtWidget- 
Geometry structure, one containing the parent's intended size for your widget, and the 
other to contain your reply to the parent's suggestion. The XtWidgetGeometry structure 
is shown in Example 7-6. 
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Example 7-6. The XtWidgetGeometry structure 
typedef struct { 
XtGecmetryMask request_node; 
Position x, y; 
Dimension width, height; 
Dimension border_width; 
Widget sibling; 
int stackmode; 
} XtWidgetGecmet ry; 
The request_mode field is a mask that indicates which other fields in the structure are set 
It is a bitwise OR of any or all of the symbolic constants shown in Table 7-1. 

Table 7-1. XtWtdgetGeometry request_mode Symbols 

Symbol 

CWX 
CWY 
CWWidth 
CWHeight 
CWBorderWidth 
CWS ibl ing 

CWStackMode 

Description 

The x coordinate of the widget's top left comer is specified. 
The y coordinate of the widget's top left comer is specified. 
The widget's width is specified. 
The widget's height is specified. 
The widget's borderwidth is specified. 
A sibling widget is specified, relative to which this widget's stacking 
order should be determined. 
A stack, mode value is present, specifying how this widget should 
be stacked relative to the widget identified as sibling. 

The sibling and stack_mode fields are used together to indicate where in the stacking 
order of its siblings your widget will be placed. The symbols for stack_mode are Above 
Below, TopIf, BottomIf, Opposite, and XtSMDontChange. (These symbols are 
used singly, not combined with OR.) Their meanings are summarized in Table 7-2. 

Table 7-2. XtWidgetGeometry stack_mode Symbols 

Stacking Flag 

Above 

Below 

TopIf 

BottomIf 

Position 

w is placed just above sibling. If no sibling is specified, w is 
placed at the top of the stack. 
w is placed just below sibling. If no sibling is specified, w is 
placed at the bottom of the stack. 
If sibl ing obscures w, then w is placed at the top of the stack. If no 
sibling is specified, then if any sibling obscures w, wis placed at the 
top of the stack. 
If wobscures sibling, then wis placed at the bottom of the stack. If 
no sibling is specified, then if wobscures any sibling, wis placed at 
the bottom of the stack. 
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Example 7-7. BitmapEdit: the query_geometry method (continued) 

DEFAULqWIDTH) ? DEFAULqWIDTH : 
cw- >bitmapEdit. pixmap_width_in_pixel s; 
answer->height = (cw->bitmapEdit.pixmap_height_inpixels > 
DEFAULTHEIGHT) ? DEFAULTHEIGHT : 
cw- >bitmapEdit. pixmap_height_inpixel s; 

if ( ((proposed->request_mode & (CWWidth I CWHeight)) 
== (CWWidth I CWHeight)) && 
proposed->width == answer->width && 
proposed->height == answer->height) 
return XtGeometryYes; 
else if (answer->width == cw->core.width && 
answer->height == cw->core.height) 
return XtGeometryNo; 
else 
return XtGeometryAlmost; 

7.7 The destroy Method 

When a widget is destroyed by the application, its destroy methods are invoked in sub- 
class to superclass order. Therefore, the destroy method for any given class needs to free 
only the memory allocated by itself; it need not worry about memory allocated by super- 
classes. 

Any server resources created by Xt (such as GCs requested through XtGetGC ( ) ) should be 
freed in the destroy method. In addition, if you called any Xlib routines, such as 
XCreateGC ( ), that allocate server- or client-side resources, be sure to free them here. Bit- 
mapEdit creates pixmaps for use in the drawing process, so it must free them. It must also 
free the GCs it allocated. 

If this is not done, then the server resources allocated for the widget will not be freed until 
the application exits. This is not a fatal problem. It matters only in applications that destroy 
widgets and then continue running for a while before they exit, which is unusual. Example 
7-8 shows the destroy method code from the BitmapEdit widget. It frees the pixmaps 
created in the initialize method shown in Example 7-1. 

Example 7-8. The destroy method 
static void 
Destroy (w) 
Widget w; 
{ 
BitmapEditWidget cw = (BitmapEditWidget) w; 
if (cw- >bitmapEdit. big_icture) 
XFreePixmap (XtDisplay (cw), cw->bitmapEdit .big_picture) ; 

if (cw->bitmapEdit. draw_gc) 
XFreeC4C (XtDisplay (cw), cw- >bitmapEdit. draw_gc ) ; 

if (cw->bitmapEdit.undraw_gc) 
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Example 7-8. The destroy method (continued) 
XFreeGC (XtDisplay(cw), cw->bitmapEdit.undrawc) ; 
if ( cw- >bitmapEdit. copyc ) 
XtReleaseGC (cw, cw->bitmapEdit, copy_gc) ; 
} 
If your widget allocated memory for any of its instance variables (or other global variables) 
using the Toolkit routines XtMalloc () or XtCalloc () (which operate just like the C 
library but add error checking), then it should free that memory here with XtFree(). 
Many widgets, including BitmapEdit, allow the application to supply the working memory, 
or the widgets can allocate it themselves. BitmapEdit maintains a flag (user_allocated) 
to indicate who originally allocated the memory. 
If your widget called XtAddEventHandler ( ) or XtAddTimeOut (), then you should 
call XtRemoveEventHandler ( ) and XtRemoveTimeOut (), respectively (these rou- 
tines are described in Chapter 9, More Input Techniques). 

7.8 Actions in the Widget Framework 

Although actions, strictly speaking, are not methods, writing them is part of the process of 
writing a simple widget. Fortunately, you have already seen action routines added from the 
application. Action routines look and work the same in the widget framework as in the appli- 
cation, except that they use instance structure fields as data instead of the application data 
structure fields. Example 7-9 shows the actions of BitmapEdit. 

Example 7-9. BitmapEdit: action routines 
/ *ARGUSED* / 
static void 
DrawCell (w, event) 
Widget w; 
XEvent *event; 
String *params; 
Cardinal *num_params; 
{ 
BitmapEditWidget cw = (BitmapEditWidget) w; 
DrawPixmaps(cw->bitmapEdit.drawc, DRAW, cw, event); 
} 
/ *ARGUSED* / 
static void 
UndrawCell (w, event) 
Widget w; 
XEvent *event; 
String *params; 
Cardinal *num_params; 
{ 
BitmapEditWidget cw = (BitmapEditWidget) w; 
DrawPixmaps(cw->bitmapEdit.undrawc, UNDRAW, cw, event); 
} 

/ *ARGUSED* / 
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Example 7-9. BitmapEdit: action routines (continued) 

static void 
ToggleCell (w, event) 
Widget w; 
XEvent *event; 
String *params; 
Cardinal *nunl_params; 
{ 
BitmapEditWidget cw = (BitmapEditWidget) w; 
static int oldx = -I, oldy = -I; 
GC gc; 
int mode; 
int newx, newy; 

/* This is strictly correct, but doesn't 
* sem to be necessary */ 
if (event->type == ButtonPress) { 
newx = (cw->bitmapEdit.cur_x + ((XButtonEvent *)event)->x) / 
cw->bitmapEdit, cel l_si ze_in_pixel s; 
newy = (cw->bitmapEdit.cur__v + ((XButtonEvent *)event)->y) / 
cw->bitmapEdit, cell_si ze_inpixel s; 
} 
else { 
newx = (cw->bitmapEdit.cur_x + ((XMotionEvent *)event)->x) / 
cw- >bitmapEdit. cel l_si z e_inpixel s; 
newy = (cw->bitmapEdit.cur__v + ((XMotionEvent *)event)->y) / 
cw- >bitmapEdit. cel l_si z e_in_pixel s; 
} 

if ((mode = cw->bitmapEdit.cell[newx + newy * 
cw->bitmapEdit.pixmap_width_i_cells ] ) == DRAWN) { 
gc = cw->bitmapEdit.undrawc; 
mode = UNDRAW; 
} 
else { 
gc = cw->bitmapEdit.draw_gc; 
mode = DRAW; 

if (oldx .'= newx II oldy .'= newy) { 
oldx = newx; 
oldy = newy; 
DrawPixmaps(gc, mode, cw, event); 
} 

static void 
DrawPixmaps(gc, mode, w, event) 
GC gc; 
int mode; 
Widget w; 
XButtonEvent *event; 
{ 
BitmapEditWidget cw = (BitmapEditWidget) w; 
int newx = (cw->bitmapEdit.cur_x + event->x) / 
cw- >bitmapEdit. cel l_s i z e_inpixel s; 
int newy = (cw->bitmapEdit.cur__v + event->y) / 
cw- >bitmapEdit. cel l_si ze_inpixel s; 
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Example 7-9. BitmapEdit: action routines (continued) 
XExposeEvent fake_event; 
/* if already done, return */ 
if (cw->bitmapEdit.cell[newx + newy * 
cw->bitmapEdit.pixmap_width_in_cells ] == mode) 
return; 
/* otherwise, draw or undraw */ 
XFillRectangle (XtDisplay (cw), cw->bitmapEdit.big_picture, gc, 
cw->bitmapEdit, cell_size_in__Dixels*newx + 2, 
cw->bitmapEdit, cell_size_in__Dixels*newy + 2, 
(unsigned int) cw->bitmapEdit, cell_size_in__Dixels - 3, 
(unsigned int) cw->bitmapEdit, cell_size_in__Dixels - 3) ; 
cw->bitmapEdit.cell[newx + newy * 
cw->bitmapEdit.pixmap_width_in_cells ] = mode; 
info.mode = mode; 
info.newx = newx; 
info. newy = newy; 
fake_event .x = cw->bitmapEdit, cell_size_in__Dixels * 
newx - cw->bitmapEdit.cur_x; 
fake_event.y = cw->bitmapEdit.cell_size in lixels * 
newy - cw->bitmapEdit.cur_y; 
fake_event.width = cw->bitmapEdit.cell_size_in__Dixels; 
fake_event .height = cw->bitmapEdit, cell_size_in__Dixels; 
Redisplay (cw, &fake_event) ; 
XtCallCallbacks(cw, XtNcallback, &info); 
} 
Notice that as in methods, the widget instance pointer passed in is declared as type Widget, 
and then. in the first line of the action, cast to the desired type. This is necessary for ANSI C 
conformance. 
An action routine in widget code can set and read fields in the widget instance structure 
passed in, while an action added from the application can access its own application data 
structure but not the widget's internal data structure because of the encapsulation rule (see 
Section 2.1.6.4). This is one of the advantages of moving this code into a widget. 
You should now be ready to go back near the end of Chapter 6, Inside a Widget, and follow 
the directions to write your first widget. You will need to review pans of both Chapter 6 and 
this chapter as the process of actually writing a widget raises new questions in your mind. 
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8 

Events, Translations, and Accelerators 

This chapter describes the complete syntax of translation tables, and 
describes a mechanism called accelerators for mapping events in one widget 
to actions in another. 
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8 
Events, Translations, 
and Accelerators 

Events drive the application. They send a great variety of information from the server to the 
client and from the user to the application. More knowledge of events is necessary both to 
use existing widgets successfully in large applications and to write widgets. 
Events are sufficiently central to X that we've devoted two chapters in this book to them. 
This chapter provides a closer look at translations and actions; Chapter 9, More Input Tech- 
niques, looks at lower-level event handlers, as well as at other sources of input. Appendix 
C, Event Reference, in Volume Five, X Toolkit Intrinsics Reference Manual, will also be use- 
ful when you need details about any of the event types. 
The basic concept and use of translations and actions has already been described. But trans- 
lation tables have a complicated syntax which can be used to do much more than the simple 
mappings you have seen until now. Translation tables can detect user-interface idioms such 
as double- and triple-button clicks or key combinations such as Shift-Meta-M. This chapter 
focuses on the more advanced features of translation tables. 
Next, we discuss a variation of translations called accelerators. Accelerators bind events 
that occur in one widget to actions in another. This is a flexible feature with many uses. One 
common use is to supply a keyboard interface to a normally pointer-driven application. By 
adding accelerators to the top-level window of the application, a keyboard event typed with 
the pointer anywhere in the application can be translated into an action in the correct widget. 
The name "accelerator" comes from the fact that many advanced users find it faster to use 
keyboard shortcuts instead of menus. 
Both translations and accelerators are resources. Therefore they are normally set by default 
in the widget code, but can be replaced or overridden by user-defined settings in resource 
files or with xrdb. In R5, a new "psuedo-resource" called XtNbaseTranslations pro- 
vides a new level of flexibility in modifying translations from resource files. Be sure to see 
Section 10.2.12 for an explanation of how translation resources should be set. As mentioned 
in Chapter 3, More Techniques for Using Widgets, it is a very good idea to specify translation 
tables and accelerator tables in the app-defaults file instead of hardcoding them in the appli- 
cation, especially while an application is under development. This lets you develop the 
translations and accelerators without recompiling the application every time you want to 
make a change. 
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8.1 Translation Table Syntax 

If you are reading this book in sequence, you've already seen translations used many times. 
However, we haven't given a formal description of their syntax or a complete listing of the 
events you can translate. 
A translation table consists of an optional directive, which specifies how the table should be 
merged with any other existing translation tables, followed by a series of production rules, of 
the form: 
[ modiJier_list ] <event> [ ,<event>... ] [ (count) ] [detail] : action([arguments ]) [ action... ] 
where brackets ([ ]) indicate optional elements, an ellipsis (...) indicates repetition, and 
italics indicate substitution of an actual modifier, event, detail, or action name. 
At a minimum, a translation must specify at least one event, specified by a predefined event 
name or abbreviation enclosed in angle brackets; a colon separator; and at least one action. 
However, a sequence of events can be specified; likewise, more than one action can be 
invoked as a result. The scope of event matching can be limited by one or more optional 
modifiers, and, in the case of some events, by a "detail" field that specifies additional infor- 
mation about the event. (For example, for key events the detail field specifies which key has 
been pressed.) Repeated occurrences of the same event (e.g., a double-click) can be specified 
by a count value in parentheses. A colon and optional white space separates the translation 

and the action. 
The examples below are all valid translations: 
<Enter>: doit ( ) 
<BtnlDown>, <BtnlUp>: doit ( ) 
<BtnlUp> (2) : doit ( ) 
Buttonl<Btn2Down>, <Btn2Up>: 

Shift<BtnDown>: doit() 

<Key>y: doit ( ) 

doit() 

invoke doitO on an EnterNotify event 
invoke doitO on a click of Button 1 
invoke doitO on a double-click of Button 1 
invoke doitO on a click of Button 2 
while Button 1 is held down 
invoke doitO on a click of any button 
while the shift key is held down 
invoke doitO when the y key is pressed 

A translation table is a single string, even when composed of multiple translations. If a trans- 
lation table consists of more than one translation, the actual newlines are escaped with a 
backslash (except for the last one), and character newlines are inserted with the \n escape 
sequence, as you've seen demonstrated in examples throughout this book. 

The following sections provide additional detail on each of the elements of an event transla- 
tion. We'll talk first about the directive, followed by event specifiers, details, modifiers, and 
counts. We'll also provide some pointers on the proper sequence of translations, and discuss 
what happens when translations overlap. 
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8.1.1 The Directive 

As we've already seen, the three possible directives are #replace, #override, or 
#augment. 
#replace says to completely replace the value of the translations resource in the 
widget. If no directive is specified, #replace is the default. 
The difference between #override and #augment is more subtle. They differ in how 
they treat event combinations in the new translation that also appear in the old. With 
#override, the new translation takes priority, while with #augment, the old one does. 
For example, say a widget has a default translation table that includes a translation for the 
Return key, and an application that uses this widget has an app-defaults file consisting of a 
translation table that applies to this widget. If the translation table in the app-defaults file 
began with #override, any translation for the Return key would take priority over the 
default translation for the Return key. On the other hand, if the translation table in the app- 
defaults file began with #augment, the default translations would take priority. 
Remember that the difference between #augment and #override is only in the treatment 
of overlapping translations. Any translations added with either directive for events that do 
not already appear in the existing translation table will always be added. 
Because of potential overlap between translations, when you are debugging your intended 
translations it is best to use #replace at first, then test with #augment or #override as 
appropriate once you are sure that the translations themselves have the desired effect. 

8.1.2 

Selecting the Events to Translate 

An X event is a packet of data sent by the server to a client in response to user behavior or to 
window system changes resulting from interactions between windows. There are 33 different 
types of events defined by X. Most (though not all-t) events can be thought of as occurring in 
a window: the pointer entering or leaving a window, pointer motion within a window, 
pointer button presses, key presses, and so on. However, most events are not sent to a win- 
dow unless the window has explicitly selected that event type; events are selected on a per- 
window basis. In Xlib programming, events are selected by specifying an event mask as a 
window attribute. Some events, which are sent to all windows regardless of whether a win- 
dow has selected them or not, are called non-maskable events. One of the most complex 
aspects of Xlib programming is designing the event loop, which must take into account all of 
the possible events that can occur in a window. 

Xt's translation manager selects the events that are specified in the current translation table 
for each widget. In translations, events can be specified either by their actual names, as 
shown in Column 1 of Table 8-1, or by means of the abbreviations shown in Column 2. A 

"POthers reflect internal changes in the window system not related to any window. For example, a MappingNotify 
event occurs in response to a change in the mappings of keysyms (portable key symbols) to keycodes (actual codes 
generated by physical keys). 

Events, Translations, and Accelerators 205 



complete reference to each event type is provided in Appendix C, Event Reference, in Vol- 
ume Five, X Toolkit lntrinsics Reference Manual. 

Table 8-1. Event Type Abbreviations in Translation Tables 

Event Type 

ButtonPress 

ButtonRelease 

KeyPress 

KeyRelease 
MotionNotify 

EnterNotify 

LeaveNotify 

FocusIn 
FocusOut 
KeymapNotify 
Expose 
GraphicsExpose 
NoExpose 
ColormapNotify 
PropertyNotify 
VisibilityNotify 
ResizeRequest 

Abbreviations 

BtnDown 
BtnlDown 
Btn2Down 
Btn3Down 
Btn4Down 
Btn5Down 
BtnUp 
BtnlUp 
Btn2Up 
Btn3Up 
Btn4Up 
Btn5Up 
Key 
KeyDown 
Ctrl 
Meta 
Shift 
KeyUp 
Motion 
PtrMoved 
MouseMoved 
BtnMotion 
BtnlMotion 
Btn2Motion 
Btn3Motion 
Btn4Motion 
Btn5Motion 
Enter 
EnterWindow 
Leave 
LeaveWindow 
FocusIn 
FocusOut 
Keymap 
Expose 
GrExp 
NoExp 
Clrmap 
Prop 
Visible 
ResReq 

Description 

Any pointer button pressed 
Pointer button 1 pressed 
Pointer button 2 pressed 
Pointer button 3 pressed 
Pointer button 4 pressed 
Pointer button 5 pressed 
Any pointer button released 
Pointer button 1 released 
Pointer button 2 released 
Pointer button 3 released 
Pointer button 4 released 
Pointer button 5 released 
Key pressed 
Key pressed 
KeyPress with Ctrl modifier 
KeyPress with Meta modifier 
KeyPress with Shift modifier 
Key released 
Pointer moved 
Pointer moved 
Pointer moved 
Pointer moved with any button held down 
Pointer moved with button 1 held down 
Pointer moved with button 2 held down 
Pointer moved with button 3 held down 
Pointer moved with button 4 held down 
Pointer moved with button 5 held down 
Pointer entered window 
Pointer entered window 
Pointer left window 
Pointer left window 
This window is now keyboard focus 
This window lost keyboard focus 
Keyboard mappings changed 
Part of window needs redrawing 
Source of copy unavailable 
Source of copy available 
Window's colormap changed 
Property value changed 
Window has been obscured 
Redirect resize request to window manager 
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Table 8-1. Event Type Abbreviations in Translation Tables (continued) 

Event Type 

CirculateNotify 
ConfigureNotify 
DestroyNotify 
GravityNotify 
MapNotify 
CreateNotify 
ReparentNotify 
UnmapNotify 

Abbreviations 

Description 

Circ 
Configure 
Destroy 
Grav 
Map 
Create 
Reparent 
Unmap 

Sucking order modified 
Window resized or moved 
Window destroyed 
Window moved due to win gravity attribute 
Window mapped 
Window created 
Window reparented 
Window unmapped 

CirculateRequest 
ConfigureRequest 
MapRequest 
MappingNotify 
ClientMessage 
SelectionClear 
SelectionNotify 
SelectionRequest 

CircRec 
ConfigureReq 
MapReq 
Mapping 
Message 
SelClr 
Select 
SelReq 

Redirect sucking order change to window manager 
Redirect move or resize request to window manager 
Redirect window map request to window manager 
Keyboard mapping changed 
Client-dependent 
Current owner is losing selection 
Selection is ready for requestor 
Request for selection to current owner 

Many of these events are handled automatically by the Toolkit separately from the translation 
mechanism. For example, Expose events are automatically sent to the expose method of 
the appropriate widget. When there is also a translation for Expose events, the action is 
called in addition to the expose method. The only reason you would need a translation for 
Expose events is to add drawing to a Core widget. Because the Core widget doesn't have 
an expose method, there is rarely, if ever, a case where there is both an expose method 
and a translation for Expose events for the same widget. The point to remember is that any 
event can be specified in a translation, even when that event is also used in some other way 
by Xt. 
GraphicsExpose and NoExpose events are useful when your application copies from a 
visible window with XCopyArea ( ) or XCopyPlane (). They notify the application when 
part of the source of the copy is obscured. If you want GraphicsExpose and NoExpose 
events, you must explicitly select them by setting the graphics_exposures GC compo- 
nent in the GC used for the copy. Then you can provide a translation for them, or if you are 
writing a widget you can have them sent to your expose method by setting the 
compress_exposure field of the Core structure to a special value, as described in Sec- 
tion 9.7.2. (While xbitmap and BitmapEdit use XCopyArea ( ) and XCopyPlane (), they 
copy from an off-screen pixmap that cannot be obscured, and therefore GraphicsExpose 
and NoExpose events are not needed. For a description of these events, see Chapter 5, The 
Graphics Context, in Volume One, Xlib Programming Manual.) 
Several of the *Notify events are automatically handled by the Toolkit. Xt places this 
information in internal structures so that it can satisfy queries for widget positions and 
geometries without querying the server. MappingNotify events are automatically 
handled; Xt gets the current keyboard mapping from the server. VisibilityNotify 
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events are handled automatically if the visible_interest field in the Core structure is 
set to True (see Section 9.5). 
With the exception of SelectionRequest, the *Request events are intended for use 
only by window managers. The selection events are described in Chapter 11, lnterclient 
Communications. 
The keyboard traversal code built into the Motif Primitive class handles EnterNotify, 
LeaveNotify, Focusln, and FocusOut events. 
Whether or not they are already handled by Xt or in translations, events can also be selected 
explicitly by installing event handlers in a widget (as described in Chapter 9, More Input 
Techniques). 

8.1.3 

Details in Keyboard Events 

As you've seen, Xt provides special event abbreviations to specify which pointer button was 
pressed or released. With key events, this approach would be a little impractical, since there 
are so many keys. Instead, the Translation Manager allows you to follow the event specifica- 
tion with an optional detail field. That is." 
<Key>: doit ( ) 
means that you want the doit () action to be invoked when any key has been pressed, 
while: 
<Key>y: doit ( ) 
means that you want the doit ( ) action to be invoked only if the y key has been pressed. 
What you actually specify as the detail field of a Key event is a keysym, as defined in the 
header file <Xll/keysymdef.h>/f Keysyms begin with an XK_ prefix, which is omitted when 
they are used in translations. 
Before we explain any further, we need to review X's keyboard model, which, like many 
things in X, is complicated by the design goal of allowing applications to run equally well on 
machines with very different hardware. 
The keyboard generates KeyPress events, and may or may not also generate Key- 
Release events. These events contain a server-dependent code that describes the key 
pressed, called a keycode. Modifier keys, such as Shift and Control, generate events just like 
every other key. In addition, all key events also contain information about which modifier 
keys and pointer buttons were held down at the time the event occurred. 
Xt provides a routine that translates keycode and modifier key information from an event into 
a portable symbolic constant called a keysym. A keysym represents the meaning of the key 
pressed, which is usually the symbol that appears on the cap of the key. For example, when 
the a key is pressed, the keysym is XK_a; when the same key is pressed while the Shift key is 
held down, the resulting keysym is XK_A (uppercase). Note that even though both the a and 

%Note, however, that this file includes foreign language keysym sets that are not always available. Only the MIS- 
CELLANY, LATIN1 through LATIN4, and GREEK sets are always available. 
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Table 8-3. Atom Details for Various Events 

Event Type 

PropertyNotify 
SelectionClear 
SelectionRequest 
SelectionNotify 
ClientMessage 

Detail Atom 

Property that is changing. 
Selection atom (such as PRIMARY). 
Selection atom (such as PRIMARY). 
Selection atom (such as PRIMARY). 
Message type. 

For MappingNot i fy, the detail can be Modi f ier, Keyboard, or Point er. Xt auto- 
matically does what is normally required to handle keyboard (and modifier) mapping 
changes. However, the Pointer detail might be used to make sure that the user has not dis- 
abled (by mismapping) any pointer button that is necessary for the safe operation of the 
application. You would simply write a translations such as <Mapping> Pointer: 
ButtonMapCheck and then call XGetPointerMapping () in the ButtonMapCheck 
action to make sure the pointer mapping is still acceptable. 
The detail values for each event type corresponds to certain members of the associated event 
structure, as shown in Table 8-4. See Appendix C, Event Reference, in Volume Five, X 
Toolkit Intrinsics Reference Manual, for more details. 

Table 8-4. Event Structure Fields Used As Translation Table Hints 

Event Type 

ButtonPress, ButtonRelease 
MotionNotify 
EnterNotify, LeaveNotify 
FocusIn, FocusOut 
PropertyNotify 
SelectionClear 
SelectionRequest 
SelectionNotify 
ClientMessage 
MappingNotify 

Event Structure Field 

button 
is_hint 
mode 
mode 
atom 
selection 
selection 
selection 
message_type 
request 

8.1.5 

Modifiers 

Certain events include as part of their data the state of the pointer buttons and special key- 
board modifier keys at the time the event was generated. The events for which this state is 
available include ButtonPress, ButtonRelease, MotionNotify, KeyPress, 
KeyRe i ea s e, Ent erNot i fy, and LeaveNot i fy. 
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For these events, you can specify a desired modifier state using one or more of the modifier 
keywords listed in Table 8-5. An error is generated if you specify modifiers with any other 
types of events. 

Table 8-5. Modifiers Used in Translation Tables 

Modifier 

Ctrl 
Shift 
Lock 
Meta 
Hyper 
Super 
Alt 
Modl 
Mod2 
Mod3 
Mod4 
Mod5 
Buttonl 
Button2 
Button3 
Button4 
Button5 

Abbreviation 

c 
s 
su 
a 

Description 

Control key is held down. 
Shift key is held down. 
Caps Lock is in effect. 
Meta key is held down. 
Hyper key is held down. 
Super key is held down. 
Alt key is held down. 
Modl key is held down. 
Mod2 key is held down. 
Mod3 key is held down. 
Mod4 key is held down. 
Mod5 key is held down. 
Pointer Button 1 is held down. 
Pointer Button 2 is held down. 
Pointer Button 3 is held down. 
Pointer Button 4 is held down. 
Pointer Button 5 is held down. 

8.1.5.1 

Physical Keys Used as Modifiers 

The meaning of the Meta, Hyper, Super, Alt, and Modl through Mod5 keywords may 
differ from server to server. Not every keyboard has keys with these names, and even if 
keysyms are defined for them in <Xll/keysyrndef.h>, they may not be available on the physi- 
cal keyboard.$ 

For example, the file <Xll/keysymdefh> includes the following definitions: 

/* Modifiers */ 

#define XK_Shift_L 
#define XK_Shift_R 
#define XK_Control_L 
#define XK_Control_R 
#define XK_Caps_Lock 

0xFFEI /* Left shift */ 
0xFFE2 /* Right shift */ 
0xFFE3 /* Left control */ 
0xFFE4 /* Right control */ 
0xFFE5 /* Caps lock */ 

:The contents of <Xlllkeysymdefh> are the same on every machine. What is different is the default mapping of 
keysyms to physical keycodes, which occurs in the server source. The only way to find out the mappings is through 
documentation (which is usually not available) or experimentation (as described in Chapter 11 of Volume Three, X 
Window System User's Guide, Second or Third Edition). 
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#define XK_Shi ft_Lock 0xFFE6 
#define XK_Meta_L 0xFFE7 
#define XIq_MetaR 0xFFE8 
#define XK_AIt_L 0xFFE9 
#define XK_AIt_R 0xFFEA 
#define XK_Super_L 0xFFEB 
#define XK_Super_R 0xFFEC 
#define XK_Hyper_L 0xFFED 
#define XK_Hyper_R 0xFFEE 

There are two things you must learn before you can 

/* Shift lock */ 
/* Left meta */ 
/* Right meta */ 
/* Left alt */ 
/* Right alt */ 
/* Left super */ 
/* Right super */ 
/* Left hyper */ 
/* Right hyper * / 
use these modifiers: 

1. Which physical key generates a given keysym, if it is not obvious from the name. 
2. Which modifiers are valid on your server. 

The best way to find out what keysym a key generates is with the xev client, which prints 
detailed information about every event happening in its window. To find out a keysym, run 
xev, move the pointer into its window, and then press the key in question. 
On the Sun SparcStation, there is only one control key, on the left side of the keyboard. It 
generates the keysym XK_Control_r,. There are two shift keys, one on each side, which 
generate the keysyms XK_Shift_L and XK_Shift_R. The Meta modifier is mapped to 
the keys labeled "Left" and "'Right." Even though there is an Alternate keyboard key, 
which generates the keysym XK_Alt_R, this key is not recognized as a modifier. There are 
no Super and Hyper keys. 
The list of valid modifiers can be displayed with the xmodmap client, as follows: 
isla% xmodmap 
xmodmap: up to 2 keys per modifier, (keycodes in parentheses): 
shift Shift_L (0x6a), Shift_R (0x75) 
lock Caps_Lock (0x7e) 
control Control_L (0x53) 
modl Meta_L (0x7f), Meta_R (0x81) 
mod4 
That is, either of the two shift keys will be recognized as the Shift modifier, the Caps Lock 
key as the Lock modifier, and either the Left or Right keys as the Meta modifier. The Left 
and Right keys are also mapped to the Modl modifier. The Alt key is not recognized as a 
modifier. 
xmodmap also allows you to add keysyms to be recognized as the given modifier. For 
example, the following command would cause the F1 function key to be recognized as mod2: 
isla% xmodmap -e 'add mod2 = FI' 
For more information on xmodmap and xev, see Chapter 11 of Volume Three, X Window Sys- 
tem User's Guide, Standard Edition. 
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following translation to prohibit both Shift and Lock from being asserted, but there is no way 
to specify that either Shift or Lock may be present: 
Shift Lock<Key>a: append () \n\ 
Shift<Key>a: appendToEndOfLine ( ) 
Note that you cannot specify both the Shift or Lock modifier and an uppercase keysym. For 
example: 
Shift<Key>A: doit () 
will have no effect, since you cannot further shift an uppercase character. The sequence !: at 
the beginning of a translation means that the listed modifiers must be in the correct state and 
that no other modifiers except the Shift and Lock keys may be asserted. In other words, !: by 
itself means the translation is triggered only if the specified key is pressed, considering case, 
and no other modifier is pressed. 
For more details on how the Toolkit handles the ins and outs of case conversion, see 
Chapter 14, Miscellaneous Toolkit Programming Techniques. A more rigorous discussion of 
how the colon modifier works is also given in Appendix F, Translation Table Syntax, in Vol- 
ume Five, X Toolkit Intrinsics Reference Manual. 

8.1.6 

Event Sequences 
The left-hand side of a translation may specify a single event or a sequence of events that 
must occur for the action to be invoked. For example, we might want a certain action to be 
invoked only if the first button is clicked twice in succession. 
Each event specified in the sequence is one of the abbreviations for an event type enclosed in 
angle brackets, optionally led by any set of modifiers and special characters, as described in 
Section 8.1.5. Each modifier-list/event pair in the sequence is separated by a comma. 
For example, the translation to perform an action in response to a button press followed by a 
release of the same button (a button click) is the following: 
<BtnDown>,<BtnUp> : doit () 
Button press events may be specified in the translation table followed by a count in parenthe- 
ses to distinguish a multiple click. The translation to detect a double click is: 
<BtnlEDwn>(2) : doit() 
or: 
<BtnlUp>(2) : doit() 
Notice that though they have the same effect for the user, these two translations are actually 
interpreted differently. The first is equivalent to saying: 
<BtnlDown>, <BtnlUp>, <BtnlDown>: doit ( ) 
while the second is equivalent to: 
<BtnlDown>, <BtnlUp>, <Btnl EDwn>, <BtnlUp>: doit ( ) 
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will cause doit ( ) to be invoked many times, once for each motion event generated by the 
pointer movement, unless the compress, motion event filter is turned on in the Core class 
structure. (This filter is described in Section 9.7.2.) 

8.1.6.2 Modifiers and Event Sequences 

A modifier list at the start of an event sequence applies to all events in the sequence. That is: 
Shi ft<BtnDown>, <BtnUp>: doit ( ) 
is equivalent to: 
Shi ft<BtnDown>, Shi ft<BtnUp>: doit ( ) 
However, if modifiers and events are interspersed, the modifier applies only to the event 
immediately following. As an extreme case to demonstrate this behavior, consider the fol- 
lowing translation: 
Ctrl<Btn2Down>, --Ctrl<Btn2Up>: doit ( ) 
which requires that the Ctrl key be depressed when pointer button 2 is pressed; however, the 
key must not be depressed when the button is released. 

8.1.6.3 Using Modifiers to Specify Button Event Sequences 

Remember that there are modifiers for specifying the state of pointer buttons as well as modi- 
fier keys. These modifiers provide another way of expressing some event sequences. For 
example, the following translation would invoke the action when the FI key is pressed while 
button 1 is being held down: 
Buttonl<Key>Fl : doit ( ) 
This is equivalent to: 
<BtnlIk)wn>, <Key>Fl : doit ( ) 
The following translations could be used to call an action when both the first and second 
pointer buttons are down, regardless of the order in which they are pressed. 
! Buttonl<Button2>: doC() \n\ 
.' Button2<Buttonl>: doC ( ) 

8.1.6.4 

Key Event Sequences 
The Translation Manager specification provides a special syntax for specifying a sequence of 
Key events--as a string. That is: 
yes  : doit ( ) 
is theoretically equivalent to: 
<Key>y, <Key>e, <Key>s: doit ( ) 
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We say "theoretically" because, at least in R4 and R5 sample implementations from MIT, the 
"yes" syntax does not work from resource files. It may or may not work in other implementa- 
tions. 

Within a sequence of key events expressed as a string (on systems where the "yes" syntax 
does work, if any), the special character ^ (circumflex) means Ctrl and $ means Meta. These 
two special characters, as well as double quotes and backslashes, must be escaped with a 
backslash if they are to appear literally in one of these strings. 

8.1.7 Interactions Between Translations 

One of the most difficult things to learn about translations is how to predict the interactions 
between overlapping translations. 

8.1.7.1 Translations in Multiple Resource Files 

Much more will be said about resource files and resource matching in Chapter 10, Resource 
Management and Type Conversion. However, it is important to make one point here. 
If several resource files contain translation tables for the same widget, only the one that takes 
priority according to file precedence and resource matching will have any effect even if all of 
them specify #augment or #override. This is because the translation table is the value 
of the resource, and only one resource value will override all other values. 
In other words, even if all the translation tables specify #augment or #override, a maxi- 
mum of two translation tables are merged by Xt: the widget's default translation table and the 
one translation table that takes priority as determined by the process of reading and merging 
all the resource files (and the command line) and then the process of resource matching. If 
you call XtOverrideTranslations ( ) or XtAugmentTranslations ( ) in the 
application, this is a third level of merging, but it is unrelated to the resource files. 

8.1.7.2 Order of Translations 

The order of translations in a table is important, because the table is searched from the top 
when each event arrives, and the first match is taken. Therefore, more specific events must 
appear before more general ones. Otherwise, the more specific ones will never be reached. 
For example, consider a text entry widget that wants to close itself and dispatch a callback 
once the user presses the Retum key, indicating that entry is complete. The widget's transla- 
tions might be: 
<Key>Return: gotData ( ) \n\ 
<Key>: insertChar ( ) 
If the translations were specified in the reverse order: 
<Key>: insertChar ( ) \n\ 
<Key>Return: gotData ( ) 
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8.1.7.3 

8.1.7.4 

insertChar ( ) would be called in response to a press of the Return key, and gotData ( ) 
would never be called. 

Keeping track of translation order is made more complicated when translations are merged. 
For example, if one of the above lines is in the default translations of a widget class, and the 
other is in a translation table in a resource file, in what order are the resulting translations? 
Though not documented in the Xt specification, it appears that the MIT implementation of Xt 
places the more specific translation first. 

Event Sequences Sharing Initial Events 

An exception to this rule of more specific translations being placed earlier in the translation 
table occurs with event sequences. One translation can contain an event or event sequence 
that appears in another translation. If the leading event or event sequence is in common, both 
will operate correctly. For example, the translations: 
<Btnl, <BtnlUp>: actionB ( ) \n\ 
<BtnlDown>: actionA ( ) 
execute actionA() when button 1 is pressed and actionB () when it is then released. 
This is true regardless of which translation appears first in the table. 
This is the reason, alluded to in Chapter 2, Introduction to the X Toolkit, why it is not pos- 
sible to bind two different actions to a single and a double click of the same button in the 
same widget. Specifying: 
<BtnlUp> (2) : quit ( ) \n\ 
<BtnlDown>, <BtnlUp>: confirm ( ) 
will invoke the confirm ( ) action on a single click and both the confirm ( ) and quit ( ) 
actions on a double click. 
This behavior was a design decision on the part of the X Consortium. Otherwise, the Intrin- 
sics could never dispatch the single-click action until the double-click interval had passed, 
since it would have no way of knowing if a second click was coming. Applications needing 
to have single and double clicks in the same widget must do so by designing the two actions 
appropriately, rather than relying on the Translation Manager to make the distinction. 

Event Sequences Sharing Noninitial Events 

If a noninitial event sequence is common between two translations, each translation will 
match only event sequences where the preceding event does not match the other translation. 
Consider the translation: 
<BtnlDown>, <BtnlUp>: act ionB ( ) \n\ 
<BtnlUp>: actionA ( ) 
When a BtnlUp event occurs, it triggers actionA ( ) only if not preceded by BtnlDown. 
The way this works is that Xt keeps a history of recent events. When each event arrives, Xt 
compares this event and its immediate history to the event sequences in a translation table. 
An event in the sequence may have already triggered an action, but that is irrelevant. Any 
translation whose final event in the event sequence matches the current event and whose 

220 X Toolkit Intrinsics Programming Manual, Athena Edition 



earlier event sequence matches the event history is matched. If there are two translations that 
can match a particular event sequence, then the translations are considered overlapping, the 
latter will override the former, and Xt will print a run-time warning message at startup (not 
waiting for the overlapping actions to be invoked). This is an exception to the rule stated 
earlier that the translation manager executes the first match. 

8.2 Accelerators 

As defined by Xt, accelerators are simply translation tables registered to map event 
sequences in one widget to actions in another. This is a general mechanism, but its name is 
based on a common use--adding keyboard shortcuts for widgets that are normally triggered 
by mouse button presses, such as Command widgets--because for advanced users a key- 
board interface is often faster. 

8.2.1 

Xt Accelerators 

Every widget has an XtNaccelerators resource, inherited from the Core widget class. 
This resource contains an accelerator table, which is identical in format to a translation table; 
it maps event sequences to action sequences. Accelerator tables can be set into the Xt- 
Naccelerators resource in all the same ways translation tables can. The widget on 
which the XtNaccelerators resource is set is the widget whose actions are to be invoked 
from events in other widgets. 
Once the XtNaccelerators resource of a widget is set, the application must call Xt- 
InstallAccelerators ( ) or XtInstallAllAccelerators ( ) to specify which 
widget will be the source of the events to invoke the actions specified in the accelerator table. 
The MIT Intrinsics documentation refers to these two widgets as the source and desti- 
nation. This can be confusing, especially since the arguments are referenced in reverse 
order in the call to XtInstallAccelerators ( ) : 
void XtInstallAccelerators (destination, source) 
Widget destination; 
Widget source; 
.lust remember that the source is the widget whose actions you want executed, and the desti- 
nation is the widget you want the events to be gathered in. To understand the use of the 
phrase install accelerators, think of the accelerators as the XtNaccelerators resource of 
the source widget, together with the actions of that widget, and the destination as the 
widget to which these actions are trangplanted (i.e., "installed"). 
XtInstallAccelerators () is always called from the application. (Widgets never 
install accelerators, because by definition they don't know about any other widgets.) In 
applications, accelerators can be installed any time, before or after the widgets are realized. 
Just before the XtAppMainLoop ( ) call is a good place. 

Events, Translations, and Accelerators 221 



As an example, we'll add accelerators to the xboxl application, which is the Athena version 
of xrowcolurnn from Chapter 3, More Techniques for Using Widgets. This application dis- 
plays two Command widgets in a Box, as shown in Figure 8-1. 

Figure 8-1. xboxl : two Command widgets in a Box 

To add accelerators requires a single line of code--a call 
Accelerat:ors (), as shown in Example 8-1. 

Example 8-1. Installing accelerators in an application 
main (argc, argv) 
int argc; 
char **argv; 
{ 
XtAppContext app_context; 
Widget topLevel, box, quit; 

to XtInstall- 

/* allc quit widget' s actions to be invoked by events in box. */ 
XtInstallAccelerators (box, quit) ; 
XtApinLoop (app_context) ; 
The actual value of the accelerator table is set through the resource mechanism. The Xt- 
Naccelerat:ors resource is set for the widget whose actions are to be invoked from 
another widget. Xt stores this accelerator table, in compiled form, in the widget's instance 
structure when the widget is created. When the application calls Xt:Tnst:all- 
Accelerat:ors (), the accelerator table stored in the widget is merged with the translation 
table of the widget that will be capturing the events. 
Example 8-2 shows a possible app-defaults file. 

Example 8-2. Specifying the XtNaccelerators resource from the app-defaults file 
*quit. label: Quit 
*pressme. label : Press me 
*quit. accelerators : \n\ 
<KeyPress>q: set ( ) notify ( ) 
This resource setting will allow a q typed anywhere in the Box widget that comprises the 
xboxl application window to invoke the quit widget's notify ( ) action (which, as you may 
recall from Section 2.4, in turn invokes the Quit: callback installed by the application). 
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widget. For example, if box had a translation of its own that matched the event sequence in 
the accelerator installed on the same widget, whether the translation or the accelerator would 
be invoked depends on whether #augment (the default) or #override had been specified 
as the accelerator directive. (This example is a little farfetched, since the Box widget defines 
no actions or translations--but it illustrates the point.) 
When using or writing widgets, event propagation is usually important only for accelerators, 
because widgets are rarely layered in such a way that any of the ones that accept input are 
obscured. 

8.2.3 

Installing Accelerators in Multiple Widgets 

If you want to install accelerators from more than one widget, you can call XtInstall- 
Accelerators ( ) once for every widget whose actions you want executable from the des- 
tination. Alternatively, you can call XtInstallAllAccelerators() just once for a 
whole application, specifying the application's top-level window as both the destination and 
the source. XtInstallAllAccelerators() recursively traverses the widget tree 
rooted at the source, and installs the accelerators of each widget onto the destination. 

For example, to install accelerators from both the quit and pressme widgets onto box, you 
could replace the call to XtInstallAccelerators ( ) shown in Example 8-1 with that 
shown in Example 8-4.-I" 

Example 8-4. Installing accelerators from both command widgets 
XtInstallAllAccelerators (box, box) ; 

You could then define an app-defaults file as shown in Example 8-5. 

Example 8-5. Accelerators resource settings for two widgets 
*quit. label : Quit 
*pressme. label : Press me 
*pressme. accelerators : \n\ 
<KeyPress>p: set() notify() 
*quit. accelerators: \n\ 
<KeyPress>q: set ( ) notify ( ) 

Because you would be most likely to specify distinct KeyPress events to invoke the actions 
in each Command widget, you would normally specify each accelerator resource separately, 
as shown above. But in the unlikely case that you wanted actions of multiple Command 
widgets to be invoked by the exact same event, you could do this instead. For example: 

*Coranand. accelerators: \n\ 
<KeyPress>: set() notify() 

"tin a more complex application, where the Box widget was not the main window but only a subarea containing com- 
mand buttons, you might instead use the call: 

XtlnstallAllAccelerators (topLevel, box) ; 
which would make the actions from only the widgets contained in box available from anywhere in the application. 
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9 

More Input Techniques 

This chapter describes how to handle events with event handlers, and how to 
use information from the event structure inside an event handler or action 
routine. It also describes how to get file, pipe or socket input, how to use 
timeouts to call a function after a delay or at particular intervals, and how to 
use work procedures to do background processing. Finally, it discusses 
some low-level features of Xt for directly interacting with the event queue. 
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9.1 Event Handlers 

An event handler is a function you provide to handle a particular type of event or group of 
event types. You register this function with a call to Xt:AddEvent:Handler () or Xt:- 
Tnsert:Event:Handler (), specifying the widget in which the events are to be monitored. 
The difference between these two functions is described below. 
You can later stop the function from being called with Xt:ReraoveEvent:Handl er ( ). On 
any widget, you can register as many event handlers as you want, each for the same or for 
different types of events. When more than one routine is registered for an event, the order in 
which they are invoked is undefined. Within widget code, event handlers are used for vari- 
ous special requirements of individual widgets. 
In general, however, event handlers are infrequently used in application or widget code. 
None of the Athena widgets use them, and, out of the 40 applications in MIT's core distribu- 
tion, only xterm and xman use them. As mentioned earlier, event handlers are useful for hand- 
ling high-volume events, such as Hot: 5_on_,'qot: i fy events, with maximum speed. An event 
handler for motion events would probably be the best way to implement a drawing program. 
However, translation tables provide good speed even for motion events on most systems. 
Event handlers would also be useful when the type of events being handled changes fre- 
quently, because there is some overhead involved in compiling and merging translation 
tables. Event handlers can also be used to handle events for which the user-configurability of 
translations is not needed or wanted, such as EnterWindow, LeaveWindow, FocusIn, 
and FocusOut events. 
Another possible use of event handlers is to speed the handling of certain events when there 
is a very large translation table. For example, editors typically have a large number of trans- 
lations for various key combinations. If an editor was to accept pointer motion as well (to 
allow drawing of simple graphics), it might pay to handle motion events in an event handler 
instead of through translations. 
The call to XtAddEventHandler ( ) specifies which events trigger the event handler func- 
tion. This is done with an event mask argument.-l In an event mask, each bit represents one 
or more event types. Symbolic constants are defined by Xlib for each event mask bit. Multi- 
ple types of events can be selected at the same time by ORing together different masks with 
the bitwise OR operator (I). Note that there is not a one-to-one correspondence between 
event masks and event types. Some event masks select only one event, but others select mul- 
tiple events. Furthermore, several of the masks select the same event type, but specify that it 
be delivered only when it occurs under special conditions. Table 9-1 shows the event masks 
and the event types they select. 

%The event mask used in XtAddEventHandler () is the same as the one used in the Xlib call XSelect- 
Input ( ). 
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Table 9-1. Event Masks and Event Types (continued) 

Event Mask 

(always selected) 
(always selected) 
(always selected) 
(always selected) 

Event Type 

ClientMessage 
SelectionClear 
SelectionNotify 
SelectionRequest 

The events that are always selected are called nonmaskable events. These can alsobe han- 
dled with an event handler, but not by specifying them in the event mask. An argument to the 
XtAddEventHandler ( ) call, non._maskabIe, is a Boolean value that, if True, speci- 
fies that the event handler should be called for nonmaskable events. This event handler then 
must branch according to which of the seven types of nonmaskable events it is passed. A 
typical nonmaskable event handler is shown in Section 9.1.2. 

9.1.1 

Adding Event Handlers 

Event handlers are added with a call to XtAddEventHandler ( ) or XtInsertEvent- 
Handler(). XtAddEventHandler () takes five arguments" the widget for which the 
handler is being added, an event mask, a flag that specifies whether or not this handler is for 
nonmaskable events (see below); the name of the handler, and optional client data. Xt- 
TnsertEventHandler() takes these and one additional argument: the position, either 
XtListTail or XtListHead. 
A list of event handlers can be registered for the same event; but the same function will 
appear only once in the list with the same client_data. If the same function/client_ 
data pair is registered again with XtAddEventHandler (), nothing will happen except 
that the event mask for that function may change. But if the same function/client_data 
pair is registered again with XtTnsertEventHandler (), the function will be moved to 
the beginning or the end of the function list. 
XtAddEventHandler ( ) or XtInsertEventHandler ( ) may be called before or after 
a widget is realized. In application code, this means the call can appear anywhere before 
XtAppMainLoop ( ). In a widget, XtAddEventHandler ( ) or XtInsertEvent- 
Handler ( ) calls are placed in the initialize or realize methods. 
Example 9-1 shows the code from xterm that registers an event handler for FocusIn and 
FocusOut events, and a gutted version of the event handler itself. 

Example 9-1. Registering an event handler, and the handler function itself 
extern void HandleFocusChange() ; 

static void VTInitialize (request, new) 
XtermWidget request, new; 
{ 
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MappingNotify is automatically handled by Xt, so it isn't passed to event handlers and 
you don't need to worry about it. The selection events are described in Chapter 11, Inter- 
client Communications. 
Because there are several nonmaskable event types, a nonmaskable event handler must be 
sure to branch according to the type of event, and throw away any event types not handled. 
You need not have all the code to handle all the types in a single event handler. Instead, you 
can handle each type in a separate handler, each registered separately. However, each han- 
dler would still need to check the event type because the entire list of them would be called 
for every nonmaskable event. 
Example 9-2 shows the registration of a nonmaskable event handler and the handler itself, 
from xman. 

Example 9-2. Adding a nonmaskable event handler 
static void 
Realize (w, valueMask, attributes) 
register Widget w; 
Mask *valueMask; 
XSetWindowAttributes *attributes; 
{ 

XtAddEventHandler(w, 0, True, 
GExpose, NLK/); /* Get Graphics Exposures */ 
} /* Realize */ 
/* ARGSUSED * / 
static void 
GExpose(w, client_data, event) 
Widget w; 
XtPointer client_data; 
XEvent *event; 
{ 
if (event->type == GraphicsExpose) 
Redisplay(w, event, NULL); /* call the expose method directly */ 
} 
This event handler is sometimes used because Xt does not normally call the expose method 
in response to GraphicsExpose events. But since R4, another way to accomplish this has 
been available. If the compress_exposure field in the Core structure is set to (Xt- 
ExposeCompressMultiple I XtExposeGraphicsExpose), Xt will call the ex- 
pose method with these events. 

9.1.3 

Removing Event Handlers 

XtRemoveEventHandler ( ) takes the same arguments as XtAddEventHandler ( ) ; if 
there are parameter mismatches, the call is quietly ignored. For example, the client data ar- 
gument may be used to distinguish between different event handlers; if the client data argu- 
ment does not match that which was passed in the XtAddEventHandler(), then 
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XtRemoveEventHandler ( ) will do nothing. XtRemoveEventHandler ( ) is also si- 
lent about failing to remove a handler that was never added or a handler that was incorrectly 
specified. 

9.1.4 

Adding Raw Event Handlers 

Xt also allows you to add event handlers without actually selecting events. The main pur- 
pose of this feature is for Xt to register functions before widgets are realized (because events 
can't be selected until windows are created during realization). Event handlers registered 
without selecting events are called raw event handlers, and are added with XtAddRaw- 
EventHandler ( ) or XtInsertRawEventHandler (), which have the same calling 
sequences as XtAddEventHandler () and XtInsertRawEventHandler (). The 
event mask indicates which events the handler will be called in response to, but only when 
these events are selected elsewhere. Raw event handlers are supported mostly because they 
are used inside Xt. They are mentioned here only for completeness--you are unlikely to 
need them. 
A raw event handler might be used to "shadow" another event handler (both added with the 
same event mask), such that until a primary event handler is added, the shadow handler will 
never be called. The primary handler will be added with XtAddEventHandler (), which 
will select events, and then both handlers will be called when the appropriate events occur. 
However, the "shadowing" technique is not necessary to assure that multiple calls to Xt- 
AddEventHandler ( ) don't result in wasted XSelectInput ( ) calls in which the event 
mask has not changed. Xt keeps a cache of the event masks of each widget, and calls 
XSelectInput ( ) only when it is necessary to change the window's event mask attribute 
in the server. 
Raw event handlers are removed with a call to XtRemoveRawEventHandler (). 

9.2 Writing Routines That Use Specific Event Data 

An event is a packet of information that the server sends to the client. Xlib takes this packet 
from the network and places it into an XEvent structure and places it on a queue until the 
client program requests it. Xt requests events from this queue and dispatches the event to the 
appropriate action routine or event handler for the widget in which the event occurred. The 
event itself is passed as an argument to the routine.% 

Actually, XEvent is a C-Language union of many event structures all the same size but with 
some different field names. The first member of the union, and of any of the individual event 
structures, is the event type. Table 9-2, later in this section, lists the event types and the 
matching event structure types. 

We'll look at the low-level routines Xt provides for directly manipulating the event queue later in this chapter. 
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Many action routines are intentionally written not to depend on the detailed information in- 
side any particular type of event, so that the user can specify translations to call the action in 
response to different types of events. For example, it is useful for an action routine normal- 
ly triggered by a pointer click to work when called in response to a key instead. Such an ac- 
tion should not depend on the event structure fields unique to button events. 

However, many other action routines, and most event handlers, do use the detailed informa- 
tion inside event structures. The first member, type, identifies which type of event this 
structure represents, and hence implies which other fields are present in the structure 

To access event structure fields other than type you need to cast XEvent into the appropri- 
ate event structure type. If you are expecting only one type of event to trigger this action, 
then you can simply declare the argument as the appropriate type, as shown in Example 9-3. 

Example 9-3. Casting the event structure by declaring action routine arguments 
/*ARGSUSED* / 
static void 
ActionA(w, event, params, nrams) 
Widget w; 
XEvent *event; 
String *params; 
Cardinal *num_params; 
{ 
if ((event->type := ButtonPress) && (event->type != KeyPress)) { 
XtWarning("ActionA invoked by wrong event type."); 
/* possible exit here */ 
} 

When an action routine or event handler depends on the fields in a particular event structure, 
it is a good practice to check the event type in that action unless you are sure that the user 
can't change the translation (and thus the events used to invoke the action). 

If you want the same code called for two event types, then you would do better to create two 
separate translations and two separate actions that each call a common routine. However, it 
is sometimes more convenient to have an action called by two different events. Example 9-4 
shows the ToggieCeii action from the BitmapEdit widget, which is called in response to 
either MotionNotify or ButtonPress events. This action inverts a pixel in the bitmap 
either if the pointer is clicked on a cell in the widget, or if it is dragged across the cell with 
the pointer buttons held down. 

Example 9-4. Handling multiple event types in an action routine 
static void 
ToggleCell (w, event) 
Widget w; 
XEvent *event; 
{ 
BitmapEditwidget cw = (BitmapEditwidget) w; 
static int oldx = -I, oldy = -I; 
GC gc; 
int mode; 
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Example 9-4. Handling multiple event types in an action routine (continued) 

int newx, newy; 

if (event->type == ButtonPress) { 
newx = (w->bitmapEdit.cur_x + ((XButtonEvent *)event)->x) / 
w->bitmapEdit, cel l_size_in_pixels; 
newy = (w->bitmapEdit.cur_y + ((XButtonEvent *)event)->y) / 
w- >bitmapEdit. cell_si ze_in_pixels; 
} 
else if (event->type == MotionNotify) { 
newx = (w->bitmapEdit.cur_x + ((XMotionEvent *)event)->x) / 
w->bitmapEdit, cel l_s i ze_in_pixel s; 
newy = (w->bitmapEdit.cur_y + ((XMotionEvent *)event)->y) / 
w->bitmapEdit, cel l_size_in_pixels; 
} 
else 
XtWarning("BitmapEdit: ToggleCell called with wrong event type\n"); 

Notice that some code is repeated to cast the event structure to the two different event types. 
With the current MIT implementation of Xlib, the positions of the x and y fields in the 
XButtonEvent and XMotionEvent structures are the same, and therefore this casting is 
unnecessary on many compilers. However, for strict ANSI C conformance these casts are 
necessary, and furthermore it is improper to depend on any particular implementation of 
Xlib. The order of the fields in one of these events could be different in some vendor's im- 
plementation of Xlib. 

9.2.1 

Event Types and Structure Names 

Table 9-2 lists the event types and the matching event structure types. The event descriptions 
in the table will give you a general idea of what each event is for. Many of these events are 
not often used in applications, and more of them are automatically handled by Xt. We've al- 
ready discussed how to use the most common event types and their abbreviations in transla- 
tion tables in Chapter 8, Events, Translations, and Accelerators. Appendix C, Event Refer- 
ence, in Volume Five, X Toolkit Intrinsics Reference Manual, provides a complete reference 
to the circumstances under which each event is generated, what it is for, and the fields in each 
of the event structures. You will need this information to write action routines that use event- 
specific data. 

More Input Techniques 237 



Table 9-2. Event Types and Event Structures 

Event Type 

KeyPress 
KeyRe i ease 
ButtonPress 
ButtonRelease 
KeymapNot i fy 
MotionNoti fy 
Ent erNot i fy 
LeaveNot i fy 
FocusIn 
FocusOut 
Expose 
GraphicsExpose 
NoExpose 
Col ormapNot i fy 
Proper tyNot i fy 
VisibilityNoti fy 
Resi zeRequest 

CirculateNotify 
ConfigureNotify 
DestroyNotify 
GravityNotify 

MapNotify 
ReparentNotify 
UnmapNotify 
CirculateRequest 

ConfigureRequest 

MapRequest 

MappingNotify 
ClientMessage 
SelectionClear 
SelectionNotify 
SelectionRequest 

Structure 

XKeyPressedEvent 
XKeyReleasedEvent 
XButtonPressedEvent 
XButtonReleasedEvent 
XKeymapEvent 
XPointerMovedEvent 
XEnterWindowEvent 
XLeaveWindowEvent 
XFocusInEvent 
XFocusOutEvent 
XExposeEvent 
XGraphicsExposeEvent 
XNoExposeEvent 
XColormapEvent 
XPropertyEvent 
XVisibilityEvent 
XResizeRequestEvent 

XCirculateEvent 
XConfigureEvent 
XDestroyWindowEvent 
XGravityEvent 

XMapEvent 
XReparentEvent 
XUnmapEvent 
XCirculateRequestEvent 

XConfigureRequestEvent 

XMapRequestEvent 

XMappingEvent 
XClientMessageEvent 
XSetSelectClearEvent 
XSelectionEvent 
XSelectionRequestEvent 

Description 

Key pressed. 
Key released. 
Pointer button pressed. 
Pointer button released. 
State of all keys when pointer entered. 
Pointer motion. 
Pointer entered window. 
Pointer left window. 
This window is now keyboard focus. 
This window was keyboard focus. 
Part of window needs redrawing. 
Source of copy unavailable. 
Source of copy available. 
Window's colormap changed. 
Property value changed. 
Window has been obscured. 
Redirect resize request to window 
manager. 
Stacking order modified. 
Window resized or moved. 
Window destroyed. 
Window moved due to win gravity at- 
tribute. 
Window mapped. 
Window reparented. 
Window unmapped. 
Redirect stacking order change to 
window manager. 
Redirect move or resize request to 
window manager. 
Redirect window map request to win- 
dow manager. 
Keyboard mapping changed. 
Client-dependent. 
Current owner is losing selection. 
Selection is ready for requestor. 
Request for selection to current owner. 
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9.3 File, Pipe, and Socket Input 

XtAppAddInput ( ) allows a program to obtain input from a file. This is not merely read- 
ing the file once, but monitoring it for further activity. Under UNIX this can be used to get in- 
put from pipes and sockets, since they are variations of files. We will demonstrate getting file 
and pipe input in this section. 

The XtAppAddInput ( ) routine takes four arguments: a file descriptor, a flag (see below), 
your function, and client_data. 

XtAppAddInput ( ) returns an ID that uniquely identifies the XtAppAddInput ( ) re- 
quest. You can use the ID to cancel the request later with XtRemovelnput (). 

One argument of XtAppAddInput ( ) is a file descriptor (this file must be open before cal- 
ling XtAppAddlnput ( ) ). Since implementation of files varies between operating systems, 
the actual contents of the parameter passed as the file descriptor argument to these routines is 
operating system-dependent. Therefore, this code is inherently nonportable. 

Possible values for the mask and their meanings are as shown in Table 9-3. 

Table 9-3. Other Input Source Masks 

Mask 

XtlnputReadMask 
XtlnputWriteMask 
XtlnputExceptMask 
XtInputNoneMask 

Description 

File descriptor has data available. 
File descriptor available for writing. 
I/O errors have occurred (exceptions). 
Never call function registered. 

Calling these argument values masks is something of a misnomer, since they cannot be ORed 
together. However, you can call XtAppAddlnput ( ) additional times to register a separate 
function (or the same function) for each of these masks on the same file descriptor. 

9.3.1 

Getting File Input 

In Example 9-5, a program called afileinput reads new characters from a file whenever they 
appear. In other words, the program will initially print to the standard output the contents of 
the file specified on the command line, and it will print any characters that are later appended 
to that file. Try the program xfileinput as follows: 
% echo "test string" > testfile 
% xfileinput testfile & 
% echo "more text" >> testfile 
A program such as this functions similarly to the UNIX command tail -f. It could be used to 
monitor system log files, or other similar files that grow. 
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The code shown in Example 9-5 opens the file and calls XtAppAddInput ( ) in main. The 
get_file_input function registered with XtAppAddInput ( ) reads and prints charac- 
ters from the file.% 

Example 9-5. Getting file input with XtAppAddlnput 
/* header files * / 

/* ARGSUSED * / 
get_file_input(client_data, fid, id) 
XtPointer client_data; /* unused */ 
int *fid; 
Xt Input Id *id; 
{ 
char buf [ BUFSIZ ] ; 
int nbytes; 
int i; 

if ((nbytes = read(*fid, buf, BUFSIZ)) := -i) 
perror("get_file_input"); 

if (nbytes) 
for (i : 0; i < nbytes; i++) 
putchar(buf[i]); 

main(argc, argv) 
int argc; 
char **argv; 
{ 
XtAppContext app_context; 
Widget topLevel, goodbye; 
FILE *fid; 
String filename; 

XtSetlanguageProc (NLKL, (XtLanguageProc)NLKL, NULL) ; 

topLevel = XtVaAppInitialize(&app_context, "XFileInput", NLKL, 
0, &argc, argv, NULL, NULL); 

if (argv[l] == NULL) { 
fprintf(stderr, "xfileinput: filename must be specified on\ 
conand line.\n"); 
exit(l); 
} 

filename = argv [ 1 ] ; 

/* open file */ 
if ((fid = fopen(filename, "r")) == NULL) 
fprintf(stderr, "xfileinput: couldn't open input file.\n"); 

Note that the code for opening and reading files is probably not portable to operating systems other than UNIX. 
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Example 9-5. Getting file input with XtAppAddlnput (continued) 
/* register function to handle that input, NULL arg 
* is client_data */ 
XtAppAddt (app_context, fileno ( fid), XtInputReadMask, 
get_file_input, NULL) ; 
XtRealizeWidget (topLevel) ; 
XtAppMainlxxp (app_context) ; 
The function registered with XtAppAddInput ( ) is called with client_data (used for 
passing in any application data), a pointer to the file descptor, and the ID of the XtApp- 
AddInput () request. You can use a call to XtRemoveInput () in the function regis- 
tered with XtAppAddInput ( ) if that function is only to be called once. One agument of 
the XtRemoveInput ( ) call is the ID of the XtAppAddInput ( ) request. 
Under some operating systems, the function registered with XtAppAddInput ( ) is called 
very frequently even when no new input is available. This is because Xt makes a system call 
to detect whether the file is "ready for reading," and some operating systems say the file is 
ready even when there is nothing new to read. The example shown above works, but it loads 
down the system much more than necessary. You may wish to check the file every quarter 
second instead of continuously, by adding and removing your input handler periodically us- 
ing timeouts (as described in Section 9.4). Under UNIX, this problem should happen only for 
files, not for pipes or sockets. 

9.3.2 

Getting Pipe Input 

The code to get pipe input is almost identical to the code just shown that gets file input. The 
only difference is that we use popen instead offopen, and change the various error messages. 
Now instead of treating the command-line argument as a filename, it is treated as a program 
run under a shell. This program's output is piped into our application. For example, here is 
an example of how to invoke this version of xpipeinput: 
spike% xpipeinput "cal ii 1989" 
November 1989 
S MTu WTh F S 
1 2 3 4 
5 6 7 8 9 10 ii 
12 13 14 15 16 17 18 
19 20 21 22 23 24 25 
26 27 28 29 30 
(Program continues to monitor pipe for further input until application exits.) 
Note that xpipeinput is reading the string "cal 11 1989" from the command line, invoking a 
shell, running the command specified by the string under this shell, reading the output of the 
shell, and then printing it on the standard output. This is an easy way to use all kinds of shell 
scripts and utilities from within a program. 
If you want your application to accept standard input, this is even easier. Remove the code 
that reads the filename from the command line and remove the popen call to open the pipe, 
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since the pipe from stdin is always open. Then use the XtAppAddInput ( ) function as 
shown in Example 9-6. 

Example 9-6. Reading stdin from an Xt application 
XtAppAddInput (app_context, fileno(stdin), XtInputReadMask, 
get_file_input, NULL) ; 

Once you have done this, you can invoke xpipeinput as follows: 
spike% cal ii 1989 1 xpipeinput 
November 1989 
S MTu WTh F S 
1 2 3 4 
5 6 7 8 9 i0 ii 
12 13 14 15 16 17 18 
19 20 21 22 23 24 25 
26 27 28 29 30 
(Program continues to monitor pipe for further input until application exits.) 
Note that in this case, xpipeinput is reading directly from stdin, and then printing the output 
to stdout. With more code, it could display this calendar in a Text widget instead. 

9.4 Timeouts 

A program may wish to be notified when a period of time has elapsed, while being able to do 
other things in the meantime. For example, a clock widget requires a periodic nudge to 
change the time it is displaying, but must also be able to redisplay itself at any time in case of 
exposure. 
This is done by using XtAppAddTimeOut (). This routine is passed a time interval in 
milliseconds, and the address of a function to be invoked when the time interval expires. As 
usual, a client_data argument can also be registered. The XtAppAddTimeOut ( ) rou- 
tine returns a handle that can be used to cancel the timeout before it triggers, if necessary. 
A timeout is automatically removed when the registered function is called. Therefore, to 
have a function called repeatedly, every N milliseconds, the registered function must add the 
timeout again by calling XtAppAddTimeOut (). 
One of the major applications of timeouts other than clocks is in real-time games. Figure 9-1 
shows the appearance of a game called xtetris after it has been played for a couple of min- 
utes. 
The object of the game is to steer falling blocks and rotate them so that they fit well into the 
existing fallen blocks.% The game is over when the blocks pile up to the top of the window. 
Every time a row is completely filled, it is removed and all the blocks above it move down 
one row. The window in which the blocks fall is a specialized widget. This game uses 
timeouts to time the falling of the blocks. 

%This game is provided with the example source code. It is an X version written by the author of a game available on 
the Macintosh called Tetris, trademark of AcademySoft-ELORG, copyright and trademark licensed to Andromeda 
Software Ltd. The original concept of the game is by Alexi Pazhitnov and Vadim Gerasimov. 
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Figure 9-1. xtetris in play 

Example 9-7 is an excerpt from a widget used by xtetris that adds the timeout. The timeout 
function itself is also shown. 

Example 9-7. xtetris: registering a timeout and the timeout function 
static XtIntervalId timer; 

static void 
StartBlock (w) 
TetrisWidget w; 
{ 
w->tetris.curx= 9; 
w->tetris.cur_y = 0; 

w->tetris, type = PickType ( ) ; 

DrawBlock (w, DRAW) ; 
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Example 9-7. xtetris: registering a timeout and the timeout function (continued) 

timer = XtAppAddTimeOut (XtWidgetToApplicationContext (w), 
w->tetris.delay, MoveDown, w); 
} 
static void 
MoveDown (w, id) 
TetrisWidget w; /* client_data */ 
Xt IntervalID *id; 
{ 
if (CanMoveDown(w)) { 
drawBlock (w, UNDRAW) ; 
w->tetris, cur_y++; 
DrawBlock (w, DRAW) ; 
CopyBlock (w) ; 
timer = XtAppAddTimeOut (XtWidgetToApplicationContext (w), 
w->tetris.delay, MoveDown, w); 
} 
else { /*block has hit bottom or other stationary blocks*/ 
UpdateCellArray (w) ; 
KillRows (w) ; 
Score (w) ; 
w->tetris.delay -= 5; 
StartBlock (w) ; 
} 
} 
Notice that in widget code, the application context is specified using XtWidget- 
ToApplicationContext ( ). 
Notice also that a timeout function is called with only one argument, client_data. Inside 
a widget, this argument is commonly used to pass in the widget instance pointer. Also notice 
that every time a block hits the bottom, the instance variable delay is decremented by 5, 
which reduces the number of milliseconds of delay used when XtAppAddTiraeOut ( ) is 
next called. In other words, the blocks fall progressively faster. 
xtetris also needs to remove a timeout in one of its routines. The user can "drop" a block to 
score extra points (if there is enough time). Whenever a block is dropped, the block is imme- 
diately moved down as far as it will go, and a new block is started. If the Drop action did 
not remove the timeout, the new block would be started with a new timeout while an existing 
timeout was already in force. This would mean that the MoveDown timeout function would 
be invoked twice in quick succession when each of these timeouts expired. Example 9-8 
shows the XtReraoveTiraeOut ( ) call in the Drop action. 

Example 9-8. xtetris: calling XtRemove TimeOut 
/*ARGSUSED* / 
static void 
Drop(tw, tevent, params, numparams) 
Widget tw; 
XEvent *tevent; 
String *params; 
Cardinal *numDarams; 
{ 
TetrisWidget w = (TetrisWidget) tw; 
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Example 9-8. xtetris: calling XtRemoveTimeOut (continued) 
XButtonEvent *event = (XButtonEvent *) tevent; 
XtRemoveTimeOut (timer) ; 
while (CanMoveDown (w)) { 
DrawBlock (w, UNDRAW) ; 
w->tetris, cur_y++; 
DrawBlock (w, DRAW) ; 
CopyBlock (w) ; 
UpdteCellArray (w) ; 
KillRows (w) ; 
score++; 
Score (w) ; 
w->tetris.delay -= 5; 
StartBlock (w) ; 
Notice that the timer ID returned from the calls to XtAppAddTimeOut () is a global 
variable. Xt calls the timeout function with only one argument, and that argument passes in 
the widget instance pointer. We could have created a structure containing the widget in- 
stance pointer and the timer ID and passed its pointer to the timeout function. But this 
wouldn't help, because the action routine in which we remove the timeout is passed with no 
client_data argument. (It has string parameters, but these are hardcoded in the actions 
table.) Therefore, we are forced to have a global variable for the timer ID. 
Note that between the time when the timeout is registered and when it triggers, the applica- 
tion processes events in XtAppMainLoop ( ). Therefore, all the widget's actions and ex- 
pose method are in operation between the invocations of the timeout function. 

9.5 

Visibility Interest 

Timeouts operate regardless of the visibility of the application. Since it is pointless for most 
games to continue operating while obscured, it makes sense to remove the game's timeouts 
when the game is partially or fully obscured (or iconified). To do this, you can set the visi- 
ble_interest field in the Core class structure to True, and then check the visible 
field of the Core instance structure periodically. When the application is fully obscured, you 
add a separate timeout to continue testing the visibility status. When the visibility status is 
satisfactory once again, the game can add its timeout again. All these changes are in the 
widget's .c file. First we set the visible_interest field to True in the Core structure: 

TetrisClassRec tetrisClassRec = { 
/* core_class fields */ 

/* visible_interest 

*/ True, 
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Second we change: 
timer = XtAppAddTimeOut(XtWidgetToApplicationContext(w), 
w->tetris.delay, MoveDown, w); 

to: 

if (w->core.visible == False) 
timer = XtAppAddTimeOut(XtWidgetToApplicationContext(w), 
250, CheckVisibility, w); 
else 
timer = XtAppAddTimeOut(XtWidgetToApplicationContext(w), 
w->tetris.delay, MoveDown, w); 
And finally, we add the timeoutfunction that continuesto check the visibility status. 
static void 
CheckVisibility(w) 
BitmapEditWidget w; /* client_data */ 
{ 
if (w->core.visible == False) 
timer = XtAppAddTimeOut(250, CheckVisibility, w); 
else 
timer = XtAppAddTimeOut(w->tetris.delay, MoveDown, w); 
} 
Unfortunately, the Core visible field is True even if a tiny sliver of the widget is visible. 
The only way to get around this is to add an event handler (or translation) for 
Vis ibi 1 i tyNot i fy events and to add an instance variable to maintain the visibility stme. 
The event handler or action would check the state field of the event, and put the game into 
hibernation if the window is only partially obscured. However, this approach has the oppo- 
site problem; it disables the game even when only a sliver is obscured. 
There is nothing you can do about the game continuing to run while being moved or resized 
with the window manager. However, using the Core visible_interest field does stop 
the game when it is iconified. 

9.6 Work Procedures 

A work procedure is an application-supplied function that is executed while an application is 
idle waiting for an event. Work procedures are registered with XtAppAddWorkProc (). 
They can perform any calculation that is short enough that the routine will return in a small 
fraction of a second. If the work procedure is too long, the user's response time will suffer. 

If a work procedure returns True, then Xt will remove it and it will not be called again. But 
if one returns False, it will be called repeatedly every time there is idle time, until the ap- 
plication calls XtRemoveWorkProc ( ). A work procedure would return True if it per- 
forms a one-time setup such as creating a pop-up widget. It would return False if it were 
continuously updating a disk file as security against a system crash or server connection 
failure. 
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You can register multiple work procedures, and they will be performed one at a time. The 
most recent work procedure added has the highest priority. Therefore, for example, if you 
want to create ten pop-up widgets during idle time, you should add ten work procedures. The 
popup that you expect to need first should be added in the last work procedure registered. 

The call to register a work procedure is shown in Example 9-9. 

Example 9-9. Registering an Xt work procedure 
static Boolean create_/Dopup ( ) ; 

: 
maln (argc, argv) 
int argc; 
char **argv; 
{ 
XtAppContext app_context; 
XtWorkProcId popup_work_ID; 
Widget topLevel; 

/* XtAppInitialize, create widgets, etc. */ 

popup_work_ID = XtAppAddWorkProc (ap_context, 
create_popup, topLevel) ; 

/* 
* popup_work_ID not actually needed because work proc 
* unregisters itself by returning True. 
*/ 
XtRealizeWidget (topLevel) ; 
XtAppMainLoop (app_context) ; 
} 
Notice that XtAppAddWorkProc ( ) returns an ID of type XtWorkProcId, which is used 
only in any subsequent call to XtRemoveWorkProc (). You can cast the returned value to 
void if you do not intend to explicitly remove the work procedure. 
The client_data argument passes application data into the work procedure. It is used 
just like the same argument in callback functions. Example 9-10 shows a work procedure to 
create a pop-up widget. 

Example 9-10. A work procedure to create a pop-up widget 
Widget pshell; 

/* work procedure * / 
Boolean 
creat e_popup (cl ient_data) 
XtPointer client_data; 
{ 
Widget parent = (Widget) client_data; 
Widget dialog, dialogDone; 
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Example 9-10. A work procedure to create a pop-up widget (continued) 

pshell = XtCreatePopupShell ( 
"pshell ", 
transientShellWidgetClass, 
parent, 
NULL, 
0 
); 
dialog = XtCreateManage]Widget ( 
"dialog", /* widget name */ 
dialogWidgetClass, /* widget class */ 
pshell, /* parent widget */ 
NULL, /* argument list */ 
0 /* arglist size */ 
); 
dialogDone = XtCreateManagelWidget ( 
"dialogDone", /* widget name */ 
conmmndWidgetClass, /* widget class */ 
dialog, /* parent widget */ 
NULL, /* argument list */ 
0 /* arglist size */ 
); 
XtAddCallback(dialogDone, XtNcallback, DialogDone, dialog); 
return(True) ; /* makes Xt remove this work proc automatically */ 
} 
Remember that Xt cannot inteupt a work procedure while it is running; the procedure must 
vo|untari|y give up control by returninz, and it must do so quickly to avoid slowinz user re- 
sponse. 
|f your app|ication has any biz jobs that it must do, the only way to do them without 
in ong delays is to write the code that does the biz job in a way that voluntaly inteupts 
sef and saves its state so that it can be restaed where it left off. One way to run such a task 
is as a work procedure, but this is only useful for tasks that need not be done before other 
application tasks can bezin. |f you want Expose processinZ to continue but no other 
cation task to bezin until your task is done, you would use the same type of code but place 
Iow-|evel event management routines in it, or make the rest of the application insensitive 
ti| the task is done. 
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It is also possible to remove and process a single event. XtAppProcessEvent () com- 
bines some (but not all) of the functions from XtAppNextEvent ( ) and XtDispatch- 
Event (). That is, while XtAppNextEvent ( ) takes the next event from the queue, what- 
ever it is, XtAppProcessEvent ( ) allows you to specify as a mask a bitwise OR of the 
symbolic constants XtIMXEvent, XtIMTimer, and XtIMAlternateInput. This lets 
you select only some of these event types for processing. In addition, XtAppProcess- 
Event ( ) actually calls XtDispatchEvent ( ) to dispatch X events, so only this one call 
is necessary. 

9.7.2 

Event Filters 

As you saw in Chapter 6, Inside a Widget, the class structure contains three Boolean fields 
that control Xt's event filters. These are compress_motion, compress_enterleave, 
and compress_exposure. Widgets set these fields to True (or in some cases other val- 
ues) when repeated events of these types are unwanted. Each would be used in different situ- 
ations. If turned on, they tell Xt to search Xlib's queue for a certain event sequence and then 
remove repeated occurrences of those events from the queue. 
When the compress_motion filter is set to True, and there is a series of Motion- 
Not i fy events on the queue (which occurs when the application gets behind in processing 
them), the filter throws out all but the last one (the most recent position). This is useful for 
widgets that need the most up-to-date position but do not need a complete history of pointer 
positions. 
The compres s_ent er 1 eave filter throws out all Ent erNot i fy/LeaveNot i fy pairs 
on the same window in which there are no intervening events. This would be used by a 
widget that is interested in enter and leave events, but not if the application falls behind. For 
example, even the Command widget sets compress_enterleave to True. It highlights 
its border when the pointer enters, and clears it when the pointer leaves. But if for some rea- 
son the widget falls behind and has not highlighted the border by the time the Leave- 
Not i fy event arrives with no intervening events, the border will not be highlighted. To see 
this, move the pointer quickly across a large panel of Command widgets such as in xmh, and 
you will see that not all of them draw and then undraw the border. 
If the compress_exposure filter field in the Core class structure is set to False or Xt- 
ExposeNoCompress, a widget's expose method is called once in response to each Ex- 
pose event in a contiguous series. Each event specifies a different rectangle of the widget 
that needs redrawing. 
With compress_exposure set to True or XtExposeCompressSeries, however, a 
contiguous series of events resulting from one user action is compressed into a single modi- 
fied Expose event and the expose method is called only once. This modified Expose 
event contains the bounding rectangle of the union of all the rectangles in the individual 
events. In this case the expose method is also passed an Xlib Region that describes in de- 
tail the area exposed. Probably the most useful value for compress_exposure is Xt- 
ExposeCompressMultiple, which compresses all the contiguous events resulting from 
multiple contiguous user actions. 
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When ORed with any of the XtCompress* symbols, the XtExposeGraphicsExpose 
symbol causes Xt to call the expose method with any GraphicsExpose events that oc- 
cur. Remember that you must set the graphics_exposures component to True in the 
GC used in XCopyArea ( ) or XCopyPlane ( ) in order to get GraphicsExpose events. 
XtExposeGraphicsExposeMerged, when ORed with an XtCompress* symbol, 
merges contiguous Expose and GraphicsExpose events together before calling the ex- 
pose method. 
The XtExposeNoExpose symbol causes Xt to dispatch NoExpose events to the expose 
method. This doesn't make much sense; if you need NoExpose events it is better to add an 
event handler or translation to handle them. 
The remaining symbol is XtExposeCompressMaximal. This symbol is dangerous and 
usually should not be used: it merges non-continuous Expose events into one event before 
calling the expose method. This is unwise because the intervening events could be 
ConfigureNotify events that change the size of the window. When this happens, the ap- 
plication will redraw itself, then receive the ConfigureNotify, but then it will not 
redraw itself in the new size because the Expose event that would trigger the drawing has 
already been removed from the queue. 
Almost all widgets except those that display a large amount of text should set this filter to 
XtExposeCompressMultiple. Text widgets can very efficiently redraw only the need- 
ed parts of the window because each character is in a fixed location. (Characters are in fixed 
locations in the Text widget because it uses fixed-width fonts--this is not applicable to 
widgets that display proportional fonts.) Therefore, it can efficiently process all the Expose 
events one at a time. 

9.7.3 

Input Sensitivity 

There are times when some widgets should be insensitive to events in which they are usually 
interested. For example, a Command widget should be insensitive when the command that it 
executes is already in operation. 

Widget sensitivity is inherited. For example, if a parent widget is insensitive, then its chil- 
dren are too. In other words, an entire box full of widgets can be set insensitive by simply 
setting the box widget insensitive. Note, however, that this process can be a little slow be- 
cause all the widgets in the box that honor sensitivity will redraw themselves dimmed or 
grayed. A widget is made insensitive from an application by calling XtSetSensitive ( ) 
with the sensitive argument set to False, or using XtVaSetValues ( ) on the Xm- 
Nsensitive resource (XtSetSensitive ( ) is slightly faster). 

Any widget that may need to be disabled for a time by the application should change its visi- 
ble appearance when insensitive. 

The widget that has one of the XtCallback* standard pop-up callback functions registered 
on its callback list will automatically be set insensitive when the callback is triggered. If the 
XtCallbackPopdown ( ) callback function is registered on this widget it will automatical- 
ly be set sensitive again when this callback is invoked. 
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10 

Resource Management 
and Type Conversion 

This chapter is a more thorough discussion of how resources work and how 
they should be used. This chapter describes in detail the resource file format 
and the rules that govern the precedence of resource settings. It also 
describes how to add your own type converter so that you can have applica- 
tion or widget-specific data set through resources. Finally, it describes 
subresources and how to use them. 
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10 
Resource Management 
and Type Conversion 

This chapter provides a thorough discussion of how resources work and how they should be 
used. First, we describe how to define resources, the complete syntax of resource files, and 
the rules that describe the precedence of one resource setting over another. For the sake of 
completeness, and to make sure that the ideas are presented in context, there is some repeti- 
tion of material that has been presented earlier. 
Next, the chapter describes the resource conversions performed automatically by Xt. As you 
may recall from the discussion in Chapter 2, Introduction to the X Toolkit, a value converter 
is invoked by Xt to convert a resource from the string form specified in resource files to the 
representation type actually used in the application or widget. For the representation types 
understood by Xt, simply listing the representation symbol (a constant beginning with Xt:R) 
in the resource list is enough to make Xt automatically perform the conversion. But if you 
create a representation type unknown to Xt, you need to write a type converter routine and 
register it with Xt before the automatic conversion can take place. We discuss both the stan- 
dard converters and how to write a new one. 
Finally, the chapter describes a mechanism Xt provides whereby widgets or applications may 
have subparts with separate sets of resources. Special routines are provided for setting and 
getting these resources. The R3 Athena Text widget used subparts to implement replaceable 
units that provide the data storage and display for text data. This allowed the same central 
code to edit a disk file or a string. But using subparts is now out of favor; both the Athena 
Text widget and the Motif Text widgets now use objects to accomplish the same modularity 
(see Chapter 14, Miscellaneous Toolkit Programming Techniques). 

10.1 Review of Resource Fundamentals 

As we've previously discussed, widgets and applications can declare some or all of their 
variables as resources. Not every variable need be a resource--only those for which values 
need to be supplied by the user (or for a widget, also by the application programmer) through 
the Resource Manager. Both applications and widgets may use nonresource variables for 
internal bookkeeping, or for storing values calculated or otherwise derived from resources. 
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the constants, a misspelling would not be noticed by the compiler, since resource names, 
classes, and representation types are simply strings. The misspelling would be considered 
a real resource at run time. Nothing would happen if it were set from the application, 
because no widget would actually use it. If, on the other hand, the misspelling were in 
the widget resource list, the application's setting of the intended resource would have no 
effect. 
Newly-defined resources may use a name, class, or type constant defined in <Xll/String- 
Defs.h> if an appropriate constant exists. Otherwise, the constant is defined in the 
widget's public header file, or for application resources, in the application itself, or in the 
application header file, if any. 
For many resources, the class name is simply the same as the resource name, except that 
the XtC prefix is used, and, the first letter of the name is conventionally capitalized. For 
example, the class name constant for the ZtNbackgroundPixel resource is 
XtCBackgroundPixel. However, when appropriate, a single class can be used for a 
group of related resources. This allows a single setting in the resource database to control 
the value of multiple resources. 
For example, a widget can have several elements that use pixel values (i.e., colors) as 
resource settings: background, foreground, border, block cursor, pointer cursor, and so 
on. Typically, the background defaults to white and everything else to black. If the 
background resource has a class of Background. and all the other pixel resources a 
class of Foreground, then a resource file needs only two lines to change all back- 
ground pixels to offwhite and all foreground pixels to darkblue: 
*Background: offwhite 
*Foreground: darkblue 

The representation type of the resource is specified by the resource_type field of the 
resource list. using a symbolic constant prefixed by XtR. Table 10-1 lists the correspon- 
dence between the XtR symbols defined by Xt, and actual C data types or X data types 
and structures. 

Table 10-1. Resource Type Strings 

Resource Type 

XtRAcceleratorTable 
XtRAtom 
XtRBitmap 
XtRBoolean 
XtRBool 
XtRCallback 
XtRCallProc 
XtRCardinal 
XtRColor 
XtRColormap 
XtRCursor 
XtRDimension 

Data type 

XtAccelerators 
Atom 
Pimmap (ofdepthone) 
Boolean 
Bool 
XtCallbackList 
see final built 
Cardinal 
XColor 
Colormap 
Cursor 
Dimension 
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If no value is found in the resource database, the value pointed to by the 
default_address field will be used instead. The type of this default value is given 
by the default_type field. If the default_type is different from the 
resource_type, a conversion will be performed automatically in this case as well. 

There are two special resource types that can be used only as the default_type. 
XtRImmediate means that the value in the default_address field is to be used as 
the actual resource value, rather than as a pointer to it (or in the case of a string, the value 
is a pointer to a string, rather than a pointer to a pointer to a string). The other special 
resource type, XtRCallProc, is a pointer to a function that will supply the default 
value at run time. We'll demonstrate the use of these values in Section 10.3.3. 

10.2 How Xt's Resource Manager Works 

Xt's resource handling is based on the resource manager built into Xlib, but Xt adds a great 
deal. While using the resource manager from Xlib is cumbersome, from Xt it is easy: to use 
resources in existing widgets, all you have to do is write the app-defaults file. 
Xt's handling of resources occurs in two stages: 
1. When the application starts up, with a call to XtApplnitialize ( ), Xt reads the app- 
defaults file, along with several other resource files, command-line options, and the 
RESOURCE_MANAGER property stored in the server by the user with xrdb. (Any, all, or 
none of these may contain data.) It merges all these sources of data into one internal 
database per screen (per display in R4, per screen in R5) that is used when each widget is 
created. 
2. Whenever you create a widget, the call to XtVaCreateManagedWidget ( ) reads the 
resource database and automatically sets widget resources to the values in the database. 
In order to explain this stage more clearly, we further divide it into two separate steps in 
the sections that follow. First, Xt compares the settings in the database to the widget's 
class and instance hierarchy, to find which settings apply to the widget being created. 
Second, Xt decides which one of the (possibly conflicting) settings that apply to that 
widget should actually be used. 

If the value of a resource is hardcoded by passing arguments to XtVaCreateManaged- 
Widget() or XtVaSetValues (), the hardcoded value overrides the value looked up 
from the resource database. 

To retrieve the value of application resources from the database, an application must make an 
explicit call to XtGetApplicationResources (), as described in Section 3.5.3. 
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Using loose bindings, the instance, class, or instance/class hierarchy may be abbreviated to 
the point where specifying the hierarchy as a single asterisk would indicate that any instance 
or class hierarchy (any widget in the application) will match. However, care should be taken 
when using loose bindings. One common mistake is to abbreviate a hierarchy too much, so 
that resource settings that were supposed to apply to only one widget now apply to several. 
This can be particularly serious (and hard to trace) when the resources being set are transla- 
tion tables or constraints. 
The resource name must be the string that appears in the resource name or resource class field 
in a resource list. This is the value of the XtN or XtC symbolic constant used in that field of 
the resource list. 
Any entry that is not a resource specification/value pair or does not match any resource for 
any widget in the application or any application resource is quietly ignored (no warning mes- 
sage is printed). This means that a slight error in the resource specification of an entry will 
cause that entry to be quietly and completely ignored. It is often difficult to detect such 
errors. 
Lines beginning with an exclamation point (!) are treated as comments. Some people have 
been using # instead, since it is currently supported in MIT's sample implementation of Xt. 
But # is not mandated in the Xt specification and therefore may be eliminated in future 
sample implementations from MIT or in a vendor's implementation. You are advised to use 
the exclamation point. (Even in the MIT implementation, # elicits warning messages from 
xrdb.) 

10.2.2 Wildcarding Resource Component Names 

R5 (and later) resource databases allow the character ? to be used to wildcard a single com- 
ponent (name or class) in a resource specification. Thus the specification: 
xmail. ?. ? .Background: antique white 
sets the background color for all widgets (and only those widgets) that are grandchildren of 
the top-level shell of the application xraail. And the specification: 
xmail. ?. ?*Background: brick red 
sets the background color of the grandchildren of the shell and all of their descendants. It 
does not set the background color for the child of the top-level shell or for any pop-up shells. 
These kinds of specifications simply cannot be done without the ? wildcard; sometimes the 
* wildcard does not provide the necessary fine-grained control. To set the background of all 
the grandchildren of an application shell widget without the ? wildcard, it would be neces- 
sary to specify the background for each grandchild individually. 
There is one obvious restriction on the use of the ? wildcard: it cannot be used as the final 
component in a resource specification--you can wildcard widget names, but not the resource 
name itself. Also, remember that the wildcard ? (like the wildcard *) means a different thing 
in a resource file than it does on a UNIX command line. 
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else 

else 
else 
else 
else 

else 

else 

/usr/lib/$LANG/app-defaults/class I 
/usr/lib/app-defaults/class 

$XUSERFILESEARCHPATH/class 
$XAPPLRESDIR/$LANG/class 
$XAPPLRESDIR/class 
$HOME/$LANG/class 
$HOME/class 

RESOURCE_MANAGER property rdb) 
$HOME/.Xdefaults 

$XENVIRONMENT 
$HOME/.xdefaults-hostname 

Command line options 

Figure 10-1. Typical resource setting search path on UNIX-based systems 

Table 10-2. % path substitutions and their meanings 

Substitution 

%N 
%T 
%S 
%L 
%1 
%t 
%c 
%C 

Meaning 

The filename without suffix. (Often the class name.) 
The category of files. (Often app-defaults, perhaps bitmaps.) 
The suffix. (Nothing for app-defaults files.) 
The language string. 
The language part of the language string. 
The territory part of the language string. 
The codeset part of the language string. 
The customization string. 

In X11R5, the default paths still have a required number of entries in a specified order, but 
the order in which substitutions appear in these path entries is no longer specified. This 
means that vendors may choose default paths for their implementations that allow auxiliary 
files to be installed in a single directory. The MIT implementation retains the substitution 
order of X11R4, except for the insertion of the "%C" customization substitution between the 
name and suffix substitutions. When using a vendor-supplied X 11R5, be sure to check your 
documentation for the default file search path. When writing a Makefile or Imakefile to 
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distribute with an application, bear in mind that app-defaults files, bitmap files, help files, and 
so on may not be installed in the "usual" places on all systems. 

For example, the XFILESEARCHPATH environment variable is a colon separated path. Under 
Sun OpenWindows, the openwin script appends the string "/usr/openwin/lib/%T/%N%S" to 
the XFILESEARCHPATH variable. The effect is that app-defaults files are found in the direc- 
tory/usr/openwin/lib/app-defaults. 
XtDisplayInitialize () reads the environment variables, makes the % syntaxes into 
paths with XtResolvePathnarae (), and uses XtFindFile ( ) to actually find the files. 
%T becomes the type arg of XtResolvePathnarae (), %S becomes the suffix arg, 
and %N is the fi.Z ename arg. Type is a category of files, such as app-defaults, help or bit- 
map. Suffix is file suffix such as .txt. So in your example, %T is app-defaults, and %N%S is 
the complete filename. 

This syntax can get much more complicated when il includes %1, %L, %t, and %c, all of 
which have to do with internationalization, and %C, which is for specifying different files for 
different types of displays (usually color and mono). %C is described in Section 10.2.11. 

If XFILESEARCHPATH is not defined, an implementation-specific default path will be used 
which contains at least 6 entries. These entries must contain the following substitutions: 

1. %C, %N, %S, %T, %L or %C, %N, %S, %T, %1, %t, %c 

2. %C, %N, %S, %T, %1 

3. %C, %N, %S, %T 

4. %N, %S, %T, %L or %N, %S, %T, %1, %t, %c 

5. %N, %S, %T, %1 

6. %N,%S,%T 

The order of these six entries within the path will be as given above, but the order and use of 
the substitutions within a given entry is implementation dependent. 
If the path begins with a colon, it will be preceded by %N%S. If the path includes two adja- 
cent colons, %N%S will be inserted between them. The suggested value for the default path 
on POSIX-based systems is: 
/usr/lib/Xll/%L/%T/%N%C%S:/usr/lib/Xll/%i/%T/%N%C%S: \ 
/usr/lib/Xll/%T/%N%C%S:/usr/lib/Xll/%L/%T/%N%S: \ 
/usr/lib/Xll/%i/%T/%N%S:/usr/lib/Xll/%T/%N%S 

266 X Toolkit Intrinsics Programming Manual, Athena Edition 



The default XUSERFILESEARCHPATH must contain at least six entries. These entries 
must contain $HOME as the directory prefix, plus the following substitutions in the following 
order: 
1. %C, %N, %L or %C, %N, %1, %t, %c 
2. %C, %N, %1 
3. %C, %N 
4. %N, %L or %N, %1, %t, %c 
5. %N, %1 
6. %N 
The order of these seven entries within the path will be as given above, but the order and use 
of the substitutions within a given entry is implementation dependent. 

10.2.5 Including Files in a Resource File 

The Xrm functions that read resources from files, XrmGetFileDatabase () and Xrm- 
CombineFileDatabase ( ) (the latter new in R5), recognize a line of the form: 
#include "filename" 
as a command to include the named file at that point. The directory of the included file is 
interpreted relative to the directory of the file in which the include statement occurred. 
Included files may themselves contain #include directives, and there is no specified limit 
to the depth of this nesting. Note that the C syntax #include <filename> is not sup- 
ported; neither Xlib nor Xt defines a search path for included files. 
The ability to include files is useful when producing a special app-defaults file for use on a 
color screen, for example, you can simply include the monochrome app-defaults file and then 
set or override the color resources as you desire. This technique is particularly useful when 
producing app-defaults files for use with the customization resource described below. 
Example 10-2 shows a hypothetical color resource file for the "xmail'" application. 

Example 10-2. The resource file 
! include the basic (monochrome) defaults 
#include "XMail" 
! and augment them with color 
*Background: tan 
*Foreground: navy blue 
*Cctrrnand* Foreground: red 
*to*Background: grey 
*subj ect*Background: grey 

Do not confuse this file inclusion syntax with the #include, #ifdef, etc. syntax provided 
by the program xrdb. That program invokes the C preprocessor to provide C include, macro, 
and conditional processing. The include functionality described here is provided directly by 
Xlib. 
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10.2.6 The Language String 

Xt's resource handling is designed to support resource files in different languages. The goal 
is to have all the language dependencies of an application in files, so that just by selecting a 
different set of resource files and localization files at run time, the application will operate 
correctly in another language." 
The language to use is selected with a language string, which is an application resource 
defined by Xt: "xnlLanguage" (no symbol XlzNxnlLanguage is defined for it). The 
default language string is NULL, which makes Xt operate in English, with all files in the loca- 
tions used prior to when the internationalization features were added. But when the *xnl- 
Language resource, or the LANG environment variable, is set to a language name such as 
"spanish," Xt looks first in certain directories for the Spanish app-defaults and user defaults 
files, before defaulting to the normal app-defaults or user defaults directories. 
Note that all app-defaults and user defaults files have the same name (the class name of the 
application); only the directory in which they are first examined for changes according to the 
language string. Therefore it is possible to have all the files for all the languages installed on 
a system at the same time. 
The search path for resource files is implementation dependent, but it is always begins with a 
language string-based directory. Each app-defaults file on UNIX-based systems is normally in 
a directory /usr/lib/Xll/$LANG/app-defaults. When the user sets LANG to "spanish," for 
example, Xt looks for an app-defaults file first in/usr/lib/Xl l/spanish/app-defaults. 
The path searched for user defaults files (which have the same name as the app-defaults file) 
is more complicated. If the XUSERFILESEARCHPATH environment variable is defined, Xt 
follows that path. If it is not defined but the XAPPLRESDIR environment variable is defined, 
Xt will look in $XAPPLRESDIR/LANG first before looking in $XAPPLRESDIR. If 
XAPPLRESDIR is not defined either, Xt looks in $HOME/LANG and then $HOME. 
The remaining resource setting sources are not affected by the language string. As described 
in the previous section, the next source of resource settings merged is the RESOURCE_ 
MANAGER property set with xrdb, or if not set, .Xdefaults, followed by the file specified by 
the XENVIRONMENT environment variable, or if not set, the .Xdefaults-host file. 
For a summary of the path of resource files searched by Xt, see Figure 10-1. 
Most western languages other than English use characters with accents or other marks. 
These are non-ASCII characters, in the second half of the ISO Latin-1 character set. Most 
fonts now in the X distribution provide glyphs (bitmaps) for these characters. Therefore, all 
you have to do is specify these characters in your app-defaults file in the directory named for 
the desired language. However, most standard English keyboards do not provide a way to 
type non-ASCII characters (and some computers can't store them). Because of this, the re- 
source file format has been augmented to provide a special syntax for specifying non-ASCII 
characters. Each character is specified using a backslash followed by a three-character octal 
number that represents the character. You can use xfd to determine the proper octal number 

'See the discussion of intemationalization in Chapters 10 and 11 of Volume One, Xlib Programming Manual, Third 
Edition. 
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to use. Just click on the desired character to have its index displayed. This index is the num- 
ber you enter in the app-defaults file. For example, Example 10-3 shows a Spanish app- 
defaults for xhello. 

Example 10-3. An app-defaults file for the Spanish language 
*hello. fontList: *courier-bold* 18"iso8859-i 
*hello. labelString: \161Hola, Mundo, 
The sequence \161 produces the inverted exclamation point that begins the Spanish exclama- 
tory sentence. It is important to know for sure that the font you choose has the desired 
glyphs. Note that iso8859-1 means ISO Latin-l, so that if you specify it in your font 
name, you are guaranteed to have all ISO-Latin-1 characters. Many of the fonts in the misc 
directory (such as the standard terminal fonts) do not include these characters. Also note that 
strings such as \161 may not work on systems that can only handle seven bit (ASCII) charac- 
ters (they ignore the eighth bit). 

10.2.7 

Screen-specific Resource Strings and Databases 

The function XResourceManagerString ( ) returns the contents of the RESOURCE_MAN- 
AGER property on the root window of the default screen of the display. This property con- 
tains the user's resource customizations in string form, and is usually set with the program 
xrdb. It is read by XtDisplayInitialize() when creating the resource database to 
be used by an application. This single RESOURCE_MANAGER property contains resources for 
all screens of a display. Until R5, there was no way for a user to specify different resources 
for different screens (for example, color vs. monochrome). 
In R5, xrdb can set resources in the SCREEN_RESOURCES property on the root window of 
each screen of a display. XtDisplayInitialize() reads the SCREEN_RESOURCES 
specifications and uses them to override the screen-independent RESOURCE_MANAGER specifi- 
cations. The resource database that is created in this way is the database of the screen, rather 
than the database of the display. If the same application is executed on different screens of a 
display, or if a single application creates shell widgets on more than one screen of a display, a 
resource database will be created for each screen, and the application instances or shell widg- 
ets will find resources in them that are appropriate for that screen. 
Recall that XtDisplayInitialize ( ) creates databases using resources from a number 
of sources other than these window properties, so in many cases resource databases on differ- 
ent screens will contain substantially the same values. Note, however, that the SCREEN_RE- 
SOURCES property can be used to set the customization resource and thereby cause 
different app-defaults files to be merged into different screen databases. Screen-specific re- 
source databases are created by Xt only as needed, so an application running exclusively on 
the default screen of a two-screen system will not have the overhead of maintaining two per- 
screen databases. 
Two new functions support screen-dependent resources and resource databases. The contents 
of the SCREEN_RESOURCES property on the root window of a screen are returned by the func- 
tion XScreenResourceString(). The database of a screen may be obtained with the 
function XtScreenDatabase(). The function XtDatabase(), which prior to R5 re- 
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10.2.8 Fallback Resources 

As you may recall from Chapters 2, 3, and 4, XtAppInitialize () has an argument in 
which you can specify fallback resources, which we didn't use. Many applications won't op- 
erate properly without their app-defaults file. Fallback resources are a defense in case the 
user doesn't install the app-defaults file, or if something happens to prevent access to it. 
They provide minimal application-specific resource settings that either allow the application 
to run safely or instruct the user to install the app-defaults file properly. 

If your app-defaults file is small, you can (and should) put the whole app-defaults file in the 
fallback resources. However, if your app-defaults is large, it probably makes more sense just 
to set one or more labels in the application to tell the user that the app-defaults file is not in- 
stalled properly or cannot be accessed. Remember that the fallback resources are used only 
if the app-defaults file is not found. Fallback resources are a NULL-terminated list of strings, 
each containing a resource setting. Example 10-5 shows how they are declared and then 
passed to XtVaAppInitialize (). 

Example 10-5. Setting fallback resources in XtApplnitialize 
main (argc, argv) 
int argc; 
char **argv; 
{ 
XtAppContext app_context; 
Widget topLevel, hello; 

static String fallback_resources[] = { 
"*hello.label: App-defaults file not installed or not\ 
accessible.", 
"*hello.font: *courier-bold*18*iso8859-1", 
NULL, /* Must be NULL terminated */ 
}; 

XtSetLanguageProc(NULL, (XtLanguageProc)NULL, NULL); 

topLevel = XtVaAppInitialize( 
&app_context, /* Application context */ 
"NoFile", /* Application class */ 
NULL, 0, /* cormmnd-line option list */ 
&argc, argv, /* conmand-line args */ 
fallback_resources, /* for missing app-defaults file */ 
NULL); /* terminate varargs list */ 

} 
Note that there is also a separate function, XtAppSetFallbackResources ( ), that can 
be used to set the fallback resources separately from the XtAppInitialize ( ) call. 
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3. Now the contents of the resource database are compared to the third component in the 
widget's instance and class hierarchies, q-u-lt and Command. As usual, anything begin- 
ning with an asterisk or anything beginning with a period (.) followed by either the 
expected class or instance name is a match. This matches all but entry 1, which is elim- 
inated. 

Before going on to the next comparison, any components that matched specifically (a. or 
* followed by either string) are removed, which results in the resource database shown in 
Example 10-8. 

Example 10-8. Resource database after final elimination of entries and components 
*background: red (entry 2) 
.background: green (entry 3) 
.background: yellow (entry 5) 
.background: violet (entry 6) 
*background: pink (entry 7) 
Now you see that we are left with only the resource names and tight or loose bindings. The 
matching process is finished, and the precedence analysis begins. The next section describes 
the precedence rules and then finishes this example to determine the priority of the finalist 
entries. 

10.2.10 

Resource Precedence Rules 

Because of the way merging works, no two resource specifications in the merged resource 
database will be alike. (Remember that we are using the term specij}cation for the part of the 
resource setting up to and including the colon.) For example, the merged database could 
never contain both of the following: 
XBitmap*box*background: green 
XBitmap*box*background: red 

because the merging process would remove the setting that appeared earlier in the list of da- 
tabase sources (or that appeared later in a single file). 

However, the database could contain two or more resource settings that apply to the same re- 
source of the same widget, because of differences in the widget class or instance hierarchy or 
the bindings. For example, the database could contain: 
XBitmap*box*background: green 
XBitmap*quit.background: red 

If the quit button is a child of box, both settings apply to the quit button's background. 
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The precedence rules are applied in order to determine the order of the finalist entries. 
1. Rule 1 specifies that a specification that contains higher components in the instance or 
class hierarchy takes precedence over one that contains only lower ones. The highest 
components that appear in our example are box and Box in entries 6 and 7. Therefore, 
these two have higher priority than any others. 
2. To choose between these two, we continue to Rule 2. Instance names (box) take prece- 
dence over class names (Box). Therefore, entry 7 has the highest precedence, followed 
by entry 6. Note that the precedence comparison of two finalists proceeds in the same 
manner as the original matching--from left to right in the entry, one component at a 
time. 
3. To determine the precedence of the remaining three entries, 2, 3, and 5, we begin again 
with Rule 1. However, Rule 1 does not apply because no two entries here specify differ- 
ent levels in the hierarchy. Entries 3 and 5 contain the q-uit level and entry 2 nothing 
(an asterisk does not count for Rule 1 because it is not a specified level--it is any level). 
Rule 2 specifies that the instance name q-uit takes precedence over the class name Corn- 
mand, and therefore entry 3 has higher priority than entry 5. Rule 3 does not apply, be- 
cause no two entries are identical except for binding. Because of Rule 4 we know that 
both entries 3 and 5 are higher priority than entry 2, because 3 and 5 state a name or class 
that is omitted in 2. 

Therefore, the final precedence is as shown here: 

i. *box*background: pink (entry 7) 
2. * Box. Conrnand. background: violet (entry 6) 
3. *quit .background: green (entry 3) 
4. * Conrnand. background: yellow (entry 5) 
5. *background: red (entry 2 ) 

People get used to the fact that they can set the resources of all the children of box with 
something like entry 7, but then are shocked to find that nothing happens when they attempt 
to override entry 7 with entry 3--entry 3 seems more specific to them. Even the following 
entry (using a class name) takes precedence over entry 3 because the rule about being higher 
in the widget hierarchy carries more weight than the rule that instance names take prece- 
dence over class names: 
*Box*background: pink (entry 7) 
Finally, a note about creating app-defaults files. Consider what happens when users specify a 
line like *Background: grey in their personal resource files. They would like to set the 
background of all widgets in all applications to gray, but if the app-defaults file for the appli- 
cation "xmail" has a specification of the form *Diaiog*Background: peach, the 
background of the dialog boxes in the xmail application will be peach-colored, because this 
second specification is more specific. So if they really don't like those peach dialog boxes, 
(pre-R5) users will have to add a line like XMaii *Background: grey to their personal 
resource files, and will have to add similar lines for any other applications that specify colors 
like "xmail" does. The reason this line works is rule 1 above: at the first level of the re- 
source specification, "XMail" is a closer match than * 
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This brings us to the specific reason that the ? wildcard was introduced in R5: any resource 
specification that "specifies" an application name with a ? takes precedence over a specifica- 
tion that omits the application name with a *, no matter how specific the rest of that specifi- 
cation is. So in RS, the frustrated users mentioned above could add the single line: 
?*Background: grey 
to their personal resource files and achieve the desired result. The sequence ?* is odd-look- 
ing, but correct. The ? replaces a component name, and the * is resource binding, like a dot 
(.). 
The solution described above relies, of course, on the assumption that no app-defaults files 
will specify an application name in a more specific way than the user's ?. If the "xmail" app- 
defaults file contained one of the following lines: 
xmail*Dialog*Background: peach 
XMail*Background: maroon 
then the user would be forced to explicitly override them, and the ? wildcard would not help. 
To allow for easy customization, programmers should write app-defaults files that do not use 
the name or class of the application, except in certain critical resources that the user should 
not be able to trivially or accidentally override. The standard R5 clients have app-defaults 
files written in this way. 
The moral of this story is that you should choose the bindings in your resource file to reflect 
how easy (or difficult) you want to make it for users to override your specifications. (But of 
course, even a specification containing only tight bindings can still be overridden by a user 
specification that also includes all tight bindings.) 
Be careful with tight bindings, however. Since there are no messages telling you which re- 
source specifications are actually being used, you can be tricked into thinking that you have 
set resources that you actually haven't. 
A useful tool for figuring out the priority of resource files is the appres utility. You specify 
the class name of the application on the command line, and appres shows you what resource 
settings that application will see when run. Note, however, that this does not tell you how 
these resource settings will actually apply to the widgets in the application, since appres has 
no knowledge of the widget instance hierarchy in your application. 
Another tactic in tracing resource settings is to build a routine into your application that gets 
and prints all the critical resources of a widget. Using XtGetResourceList ( ) you can 
get the list of resources supported by a widget class. Then you can query each of those re- 
sources and print most of them out. Remember that certain resources are compiled into inter- 
nal forms, so you can't print out translation tables, accelerator tables, or callback lists. It may 
also be difficult to interpret other values, since many of them will have already been convert- 
ed from the string form in the resource file into the most convenient internal form. For ex- 
ample, colors will have been changed from strings such as "red" into a pixel value (a number 
which could change each time the application is run). 
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In R5, there is a new resource, XtNbaseTranslations, that can be used by an applica- 
tion developer to specify a base set of translations that will be correctly overridden, augment- 
ed, or replaced by the value of the XtNtranslations resource. Note that this is an Xrm 
resource, but is not a widget resource in the usual Xt sense of the word (the Xt specification 
uses the term "pseudo-resource")--it does not correspond to an instance field in Core or any 
other widget class, and it cannot be set with XtSetValues () or queried with XtGet- 
Values (). The value of the translations field of the Core widget is handled specially 
by the Xt resource management code. The final value for a widget's translations are obtained 
as follows: 
1. The default value of a widget instance's translations are obtained from the Core widget 
class field tm_table. These translations are specified by the widget writer. 
2. When a widget is initialized, the Intrinsics' resource management code looks up the value 
of the XtNbaseTrans lat ions resource for that widget, and if it exists, uses the trans- 
lations it specifies to replace, override, or augment the widget's default translations. 
These translations are intended to be specified exclusively by the application developer in 
the application's app-defaults file. 
3. Finally, the value of the XtNtranslations resource is looked up for the widget, and 
if it exists the value is used to replace, override, or augment the widget's translations 
(which may have once already been replaced, overridden, or augmented). These transla- 
tions are intended to be specified by the end user of the application. 

For maximum flexibility to the user, all R5 applications should specify translations in a re- 
source file using the XtNbaseTranslations resource rather than with XtNtransla- 
tions. If the same resource file is to be used by applications compiled under both the R5 
and R4 versions of the Intrinsics, then the resource file should specify the application's trans- 
lations as the value of both resources. Under R4, the XtNbaseTranslations resource 
will be ignored, and under R5, any value of the XtNtranslations resource specified by 
the user will override the value specified in the application's app-defaults file. 

10.3 Type Conversion 

You already know that Xt is capable of converting resource values from the string representa- 
tion specified in resource files to the actual type required in code. In fact, Xt does so auto- 
matically if the resource list is properly written. This section describes this process in more 
detail, and tells you how to create converters for converting your own data types. 

In R4, a new set of interfaces for type converters was introduced. The new interfaces support 
display-specific conversions and better control of converted-value caching. This section de- 
scribes these new interfaces, but does not describe the older ones. Be aware that many exist- 
ing widgets and applications still use the older interfaces. 

280 X Toolkit Intrinsics Programming Manual, Athena Edition 



Table 10-4 lists those converters automatically recognized by Xt. 
Table 10-4. Other Built-in Converters 

From 

XtRColor 
XtRPixel 
XtRInt 

XtRPixel 
XtRColor 
XtRBoolean 
XtRBool 
XtRColor 
XtRDimension 
XtRFloat 
XtRFont 
XtRPixel 
XtRPixmap 
XtRPosition 
XtRShort 
XtRUnsignedChar 

Description of Converter 

Converts an XColor structure to a pixel value. 
Converts a pixel value to an XColor structure. 
Converts an int to a Boolean. 
Converts an int to a Boolean. 
Converts an int to an XColor. 
Converts an int to a Dimension. 
Converts an int to a float. 
Converts an int to a Font. 
Converts an int to a pixel value. 
Converts an int to a Pixmap. 
Converts an int to a Position. 
Converts an int to a short. 
Converts an int to an unsigned char. 

For example, the default value of the Core resource XtNborderPixmap is set as shown in 
Example 10- l 0. 
Example 10-10. A resource definition converting an integer to a pixmap 
static XtResource resources[ ] = { 

{ 
XtNborderPixmap, 
XtCPixmap, 
XtRPixmap, 
sizeof (Pixmap), 
XtOffsetOf(CoreRec, core.border_pixmap), 
Xtate, 
(XtPointer) XtUnspecifiedPixmap 
), 

} 
The specified default value XtUnspeci f iedPixmap is an integer defined to have a value 
that does not equal the constant CopyFromParent or any valid Pixmap ID. The ini- 
tialize method for the Core widget class checks for this value, and does not set the 
background window attribute unless the application or a resource file has set the 
XtNborderPixmap resource to some value other than the default. 
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Example 10-12. A resource definition using XtRCallProc 
static XtResource resources[ ] = { 

{ 
XtNscreen, 
XtCScreen, 
XtRPointer, 
sizeof (int), 
XtOffsetOf (CoreRec, core. screen), 
XtRCal 1Proc, 
(XtPointer) XtCopyScreen 
}, 

}; 
Example 10-13 shows an example of an XtResourceDe faul t Proc. 

Examp 10-13. An examp ofan XtResourceDeultProc 
/*ARGSUSED*/ 
void XtCopyScreen(widget, offset, value) 
Widget widget; 
int offset; 
XrmValue *value; 
{ 
value->addr = (XtPointer)(&widget->core.screen); 
} 

10.3.4 

Registering Type Converters 

As noted earlier, not every representation type symbol defined in <XI l/StringDefs.h> is sup- 
ported by a built-in converter, though Motif and the Xmu library do provide some of the most 
important converters that are missing in Xt. In addition, you can define your own resource 
types, and write converter routines to convert from a string representation in a resource file to 
the appropriate data type. (You can write converters from any type to any other type, but 
converters from String are by far the most useful.) 

Table 10-5 lists the converters from XtRString provided by the Xmu library. 
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Table 10-5. Xmu Converters 

Fl'om 

XtRString 

XtRFunction 

XtRBackingStore 

XtRBitmap 

XtRCursor 

XtRGravity 
XtRJustify 

XtRLong 
XtROrientation 

XtRShapeStyle 

XtRWidget 

XtRCallback 

Description of Converter 

The XmuCvtStringToBackingStore converter 
converts the sngs "NotUseful", "WhenMapped", 
and "Always" (in any case) into the corresponding 
constants (in proper case) for use in setting the back- 
ing_store window attribute. (See Volume 
One, Xlib Programming Manual, for details on back- 
ing store.) 
The XmuCvtStringToBitmap converter takes the 
string filename of a file in standard X l I bitmap format 
and creates a one-plane pixmap containing that bitmap 
data. 
The XmuCvtStringToCursor and XmuCvt- 
StringToColorCursor converters convert one of 
the standard cursor names (from <XII/cursorfont.h), a 
font name and glyph index of the form "FONT 
fontname index [[font] index]", or a bitmap file name 
as in XtRPixmap below, and converts it to an X 
Cursor. 

The XmuCvt St r ingToJus t i fy converter converts 
the strings "right", "left", or "center", in any case, to 
an enumeration constant suitable for use by a justify 
resource. This converter is used by the Athena Label 
widget. 
Converts a string to a long integer. 
The XmuCvtStringToOrientation converter 
converts the strings "horizontal", or "vertical", in any 
case, to an enumeration constant suitable for use by an 
orientation resource. This converter is used by the 
Athena Scrollbar widget. 
Converts the strings ShapeRectangle, ShapeO- 
val, ShapeEllipse, and ShapeRoundedRec- 
tangle in shape style constants, for use in making 
Xmu calls that access the Shape extension. 
The XmuCvtStringToWidget and XmuNewCvt- 
StringToWidget converters convert a widget name 
into the corresponding widget ID. These are old-style 
and new-style converters respectively. This convert is 
commonly used to specify the relative positions of the 
children of constraint widgets, as in the Athena Form 
widget resources fromHoriz and fromVert. Motif 
1.2 provides its own String-To-Widget converter. 
Converts a function pointer to a callback list contain- 
ing that function. 
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Whether defined in Xmu or in your own program, a converter other than those built into Xt or 
Motif must be registered with a call to XtAddConverter() or XtSetType- 
Converter ( ) before a resource list is used that references the converted types. Resource 
lists are used when widgets are created or when the application calls XtGet- 
ApplicationResources (). In the application, a converter must be registered after 
XtApplnitialize ( ) but before XtGetApplicationResources (). 
Within a widget, the class_initialize method is the standard place to register type 
converters. This method is responsible for doing processing that should be done only once 
when the first instance of a particular class is created. 
Example 10-14 shows the code needed to register the XmuCvtStringToJusti fy conver- 
ter in a widget. As noted above, this converter would be used for a resource (such as the 
Athena Label widget's XtNj ust i fy resource) designed to give the user the option of justi- 
fying text (or a graphic object) to the right, left, or center of a widget.% 

Example 10-14. Registering a type converter 
static void 
ClassInitialize ( ) 
{ 

XtSetTypeConverter(XtRString, /* source type */ 
XtRJusti fy, /* target type * / 
XmuCvtStringToJustify, /* converter routine */ 
(XtConvertArgList) NULL, 
/* args for converter routine */ 
0 /*# args for converter routine */ 
XtCacheAll, /* caching instructions */ 
NULL) ; /* destructor function */ 
} 
Note that XtSetTypeConverter ( ) was added to Xt in R4. Its predecessor, XtAppAdd- 
Converter (), is still available and can still be used, but has reduced functionality. Xt- 
AppAddConverter ( ) cannot be used for conversions that require a server query (such as 
those involving colors or fonts), and does not provide the caching control provided by Xt- 
SetTypeConverter (). Note that the explicit application context version of the call 
(XtAppSetTypeConverter ( ) ) is not used in this case, because the class_initial- 
ize method does not pass in a widget from which the application context could be deter- 
mined. 
The first two arguments of XtSetTypeConverter () are the source and target type, re- 
spectively, specified using XtR symbolic constants defined in <Xll/StringDefs.h> (or defined 
in an application header file or the widget public header file if the type is not standard in Xt). 

-While it may seem a little backwards to describe how to add a converter before we say how to write one, the avail- 
ability of the Xmu converters makes it likely that you would in fact want to add converters you haven't written. 
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The third argument is the name of the converter routine, which by convention contains the 
string Cvt. The Xmu converters all add the prefix Xmu. 
The fourth and fifth arguments of XtSetTypeConverter ( ) are an argument list that will 
be passed to the converter routine when it is called. Some converter routines require infor- 
mation about the context in which the converter is called. This is usually passed in via an 
XtConvertArgRec structure, as described in the next section. If no arguments are needed, 
the fourth and fifth arguments of XtSetTypeConverter() can be NULL and 0 
respectively. 
The sixth argument specifies whether the results of the conversion should be cached. The ba- 
sic symbols are XtCacheNone, XtCacheAll, and XtCacheByDisplay. Expensive 
conversions should be cached. Xt caches resource values to avoid repetitive conversions of 
the same value, which are common in an application made up of many identical widgets. It 
is especially important to cache conversions that require round-trips to the server, such as 
color, font, and atom conversions. But it is wasteful of memory to cache silly conversions 
such as XtCvtStringToGeometry, which actually doesn't do any conversion or even 
validity checking. (The XtRGeometry representation type is a geometry string, as defined 
by XParseGeometry(). It takes no conversion to convert XtRString to 
XtRGeometry. The converter could at least test the string to make sure it looks like a ge- 
ometry string.) Another benefit of caching is that Xt remembers unsuccessful conversions 
and efficiently generates warning messages without attempting any conversion more than 
once. 
The symbol XtCacheRefCount can be ORed with any of the above values, in which case 
Xt keeps track of how many widgets still exist that used a converted value, and frees the 
cached value when the count reaches zero. The application, if it uses the converted value in 
a call to XtGetApplicationResources ( ), is also counted as one reference. Reference 
counting is needed only if an application destroys widgets whose resource values may take 
up extensive space. Because reference counting takes up space and requires time, it should 
not be done unless necessary. To control reference counting on a widget-by-widget basis, an 
application must explicitly set the XtNinitialResourcesPersistent resource to 
False for each widget whose conversions are to be reference counted. These should be 
widgets that might be destroyed before the application exits. 
The seventh argument of XtSetTypeConverter ( ) is a pointer to a procedure called a 
destructor. If the reference count for a particular resource reaches zero, Xt calls the destruc- 
tor function, and removes the resource value from the conversion cache. The destructor will 
also be called when XtCloseDisplay() is called if the converter was registered with 
XtCachePerDisplay. Before calling XtCallConverter () or XtConvertAnd- 
Store ( ) to convert a value, the client must allocate memory in which to place the result. 
The job of the destructor is to deallocate this memory. If you are allowing Xt to convert data 
automatically, by declaring a resource list, Xt allocates the memory, and you don't need a 
destructor (so specify NULL). If you plan to call XtCallConverter () from an applica- 
tion, and you allocate memory statically for the converted value, you don't need a destructor 
function and can specify NULL for this argument. A destructor is needed only if you allocate 
memory dynamically for an explicit call to XtCallConverter (). (Remember that refer- 
ence counting happens only if the converter is registered with XtCacheRefCount set and 
XtNinitialResourcesPersistent set to False for at least one widget. If these 
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In most cases, you will use XtWidgetBaseOffset in widgets, gadgets and objects, as 
shown in Example 10-15. 

When registering a type converter in an application rather than a widget, the structure field 
specified in the argument list shown in the example would be a field of the AppData struc- 
ture instead of the instance part structure, and CoreRec would be replaced by AppData. 

10.3.5 

Explicitly Invoking a Converter 

Converters are normally invoked by Xt because the types they convert are specified in a re- 
source list. But this is not the only way in which converters can be invoked. It is possible to 
manually invoke type converters, the easiest way being XtConvertAndStore ().% This 
may be useful in an application, such as for reading an icon pixmap from a file using a con- 
verter, or you may need to explicitly invoke a converter from within a converter you want to 
write. (Converter routines can themselves invoke other converters directly.) 

One possible manual use of type converter routines is in the processing of the string parame- 
ters passed to action routines. Perhaps in the action routine itself it is more convenient to 
have some parameters converted to another form. For example, if an action is passed the 
string "True," the action code might prefer to convert this parameter to a Boolean value. The 
CvtStringToBoolean converter understands many strings that would be interpreted as 
Boolean, such as "Off, .... On," "True," "False," "No," and "Yes," in upper, lower, or mixed 
case. It saves code to use the converter rather than comparing a string to all these strings in 
your own code. Example 10-16 shows an action routine of the Athena Text widget in which 
a converter is manually invoked. 

Example 10-16. Manually invoking a type converter 
static void 
DisplayCaret(w, event, params, numparams) 
Widget w; 
XEvent *event; /* CrossingNotify special-cased */ 
String *params; /* Off, False, No, On, True, Yes, etc. */ 
Cardinal *numparams; /* 0, 1 or 2 */ 
{ 

if (*num_params > 0) { /* default arg is "True" */ 
XrmValue from, to; 
from.size = strlen(from.addr = params[0]); 
if (XtConvertAndStore(w, XtRString, &from, XtRBoolean, &to) 
== False) 
XtAppError(XtWidgetToApplicationContext(w), 
"DisplayCaret action: String to Boolean\ 
conversion failed"); 

%XtConvertAndStore () replaced XtConvert ( ) in R4. Both have the same arguments, but XtConvert- 
AndStore ( ) returns Boolean while XtConvert ( ) returns void. XtConvertAndStore ( ) 's remm value 
indicates whether the conversion succeeded or failed. XtConvertAndStore ( ) also implements new display-spe- 
cific conversion, caching and reference counting features. 
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10.3.6.1 

When a nonstandard type converter that uses quarks is defined and registered in widget code, 
the XrmStringToQuark calls are normally placed in the class_initial ize method 
just before the XtSetTypeConverter ( ) call. 

Defining the Default Value 

When performing conversions, such as from strings to fonts or colors, for which there is no 
string representation that all server implementations will necessarily recognize, a type con- 
verter should define some set of conversion values that the converter is guaranteed to succeed 
on, so that these can be used as resource defaults. 
For example, Xt's default string-to-pixel converter recognizes the symbols XtDefault- 
Foreground and XtDefaultBackground. As part of its conversion, it tests for these 
values, and establishes the appropriate value based on the string value. The code is shown in 
Example 10-18. 

Examp 10-18. Testing raspechcasedeu# vae 
/* 
* CompareISOLatinl is an undocumented Xt function, allowed 
* since this converter is within Xt. In your converters, 
* you would use XmuCompareISOLatinl. 
*/ 
if (CompareISOLatinl(str, XtDefaultBackground) == 0) { 
*destructor_data = False; 
if (pd->rv) 
done(Pixel, BlackPixelOfScreen(screen)) 
else 
done(Pixel, WhitePixelOfScreen(screen)); 
} 
if (CompareISOLatinl(str, XtDefaultForeground) == 0) { 
*destructor_data = False; 
if (pd->rv) 
done(Pixel, WhitePixelOfScreen(screen)) 
else 
done(Pixel, BlackPixelOfScreen(screen)); 
} 

10.4 Subparts and Subresources 

A subpart is a section of a widget that is replaceable but that cannot operate independently. 
It is just a further subdivision of the widget into smaller pieces. Gadgets and objects usually 
provide a more elegant way to do this. 

Subresources allow subparts of a widget to have separate sets of resources. Since the R3 
Athena Text widget was the only example of the use of subresources in MIT's core distribu- 
tion, we'll describe how Text used subparts and subresources so you can understand the 
motivation behind them. You can then compare this concept with the current Athena Text 
widget which is implemented using objects. Motif 1.1 and 1.2 also use subresources to fetch 
data that isn't part of the primary widget structure. This happens for resource data that is 
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shared among widgets (gadget caching) or that can't reside in the primary widget due to bio 
nary compatibility (e.g., VendorShell resources). 
The R3 Text widget has three parts: the source, the sink, and the coordinator widget. The 
source subpart manages the storage of data and the sink subpart manages how it is displayed. 
The coordinator is the central widget that manages the communication between the source 
and the sink, and is inoperable without them. Both the source and the sink are replaceable 
pieces of code. Xaw provides only one source, which edits a string or disk file, and only one 
sink, which displays text in one color and in one font. The idea of providing the subparts in 
the first place is that they would allow enhancements to be made without changing the basic 
editor functionality that is in the coordinator. For example, only the source and sink would 
need replacing in order to implement a multifont and/or multicolor text widget. 
Each subpart has its own resource list so that it truly can be replaced without any modifica- 
tions to the central widget. These are the subresources. 

The Hook Methods 

The initialize_hook, Set_values_hook, and get_values_hook methods are 
used by widgets that have subparts. They have the same function as their nonhook counter- 
pans, except that they process only the resources of a subpart, and any subpart instance fields 
that depend on the subpart resources. These methods are called immediately after their 
nonhook counterparts. 
However, the initialize_hook and set_value_hook methods have become obsolete 
in R4 because their arguments have been added to the initialize and set_values 
methods. The hook methods are still called for compatibility with existing widgets, but new 
widgets should move the code that would have been in the hook methods into i ni t ial i z e 
and set_values. 
The get_values_hook method is passed a single copy of the widget instance structure 
(the newcopy already modified in the nonhook methods), and the argument list passed to the 
Xt routine that triggered the method. The set_values and get_values_hook methods 
simply take this widget ID and argument list and pass them to XtSetSubvalues () or 
XtGetSubvalues ( ) respectively. The initialize method uses the contents of the ar- 
gument list to validate resource settings for subparts and to set nonresource subpart data. 
The get_values_hook method is still used in R4. Example 10-19 shows the 
get_values_hook for the AsciiSrc subpart of the R3 Text widget (somewhat simplified to 
show the essential elements). 

Example 10-19. Simplified get_ values_hook method of the AsciiSrc subpart of the Text widget 
static void 
GetValuesHook (src, args, nun%_args) 
XawTextSource src; 
ArgList args; 
Cardinal * nu_args; 
{ 
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11 

Interclient Communications 

This chapter discusses communication through the X server between an 
application and the window manager, and between two applications. The 
application--window manager communication is performed by code in the 
Shell widget. The application sets shell resources to control this communica- 
tion with the window manager. Applicationmapplication communication is 
usually done with a process called selections. This form of communication is 
already implemented in most widgets that display text, but you may want to 
implement it in your own custom widgets. Selections can also pass other 
kinds of data such as graphics. How to use the Motif Clipboard is also 
described. Finally, the concepts behind Motif 1.2 drag-and-drop are 
described. 
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11 
Interclient Communications 

Applications share the server with other clients. Server resources, such as screen space and 
colormaps, must be used in a responsible, consistent manner so that applications can work 
effectively together. In most window systems, the window system itself embodies a set of 
rules for application interaction. However, the X Protocol, Xlib, and Xt were all specifically 
designed to avoid arbitrary conventions, so that they provide "mechanism, not policy." 

Instead, the conventions covering interclient communication are described in a separate doc- 
ument, adopted as an X Consortium standard in July, 1989, called the Inter-Client Commu- 
nication Conventions Manual (ICCCM). This chapter will not fully describe the ICCCM, 
because the job of implementing its rules is given over to a special client called the window 
manager and a special widget class called Shell and its subclasses.'t" As a result the details of 
the ICCCM are, for the most part, irrelevant to the application writer's needs. Widget writers 
may need to refer to it when implementing selections. 

In X Toolkit programs, the Shell widget returned by XtAppInitialize ( ) and used as the 
top-level window of the application automatically handles most of the required interactions 
with the window manager. However, the Shell widget needs additional information in certain 
areas. For example, the application needs to provide an icon pixmap so that the window 
manager can iconify it properly. The first section in this chapter describes how to set Shell 
resources to control how an application interacts with the window manager. This portion of 
the chapter is for application writers, regardless of whether you need to write widgets for 
your application. 

The ICCCM defines the required information that must be sent by the client. The Shell 
widget class takes care of sending this information. 

In X Toolkit applications, widgets can communicate with other widgets using a mechanism 
called selections, which in turn is based on an X mechanism for common storage called pro- 
perties. Whether the widgets involved in transferring selections are part of the same applica- 
tion or different applications is irrelevant. The communication between widgets takes place 
without input from the application. However, it can be used as a means of communication 
between applications. The second major section in this chapter will describe these concepts 
and how to implement selections between your own custom widgets. Only if your 

" If you do need to look up certain details of the ICCCM, see Appendix L, Inter-Client Communication Conventions, 
in Volume Zero, X Protocol Reference Manual. The ICCCM is also included in troff source form in the standard X 
distribution from MIT. 
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application requires a custom widget that must communicate with other widgets should you 
actually have to write this code. Thus, this part of the chapter is primarily for widget writers. 

11.1 

Window Manager Interactions 

The window manager was introduced in Chapter 1, Introduction to the X Window System, but 
little mention of it has been made since then. You may recall that the window manager is just 
another client running on a server, except that it is given special authority to manage screen 
space and other limited server resources like colormaps.% To let the window manager do a 
better job of mediating competing demands of the various clients, each client gives the win- 
dow manager information called window manager hints. These hints specify what resources 
each client would like to have, but they are only hints; the window manager is not obligated 
to honor them, and the client must not depend on them being honored. 

Application code has little to do to interact properly with the window manager. The Shell 
widget returned by XtAppTni ti ali ze () takes care of setting the essential window man- 
ager hints. However, there are a number of optional window manager hints that the applica- 
tion may wish to have passed to the window manager. This is done mainly by setting 
resources of the Shell widget. Also, there are variations in window managers and it takes 
some effort to make some applications work equally well under all of them. 
The next few sections describe the various resources of the Shell widget, including how and 
when they should be set. Because the Shell widget is part of the Xt standard, these resources 
are present when writing applications with any widget set. 

11.1.1 

Shell Subclasses 

There are several types of Shell widgets. The Shell widget class itself, specified by the class 
structure pointer shellW-idgetClass, is never instantiated directly in applications. Only 
its subclasses are used. You have seen two subclasses of the Shell widget used earlier in this 
books: the one used for the application's top-level widget and the one used for popups. The 
application's top-level widget is created by passing the class structure pointer 
applicationShellWidgetClass as the widget class argument to XtAppCreate- 
Shell(); this call is also made internally by XtAppInitialize(). Popup shells for 
dialog boxes are created by passing transientShellWidgetClass as the widget class 
argument to XtCreatePopupShell (). There are two other subclasses of Shell that are 
commonly used in applications. One is the OverrideShellWidgetClass, passed to 
XtCreatePopupShell ( ) when the shell is used for pop-up menus. The convention is 
this: the shell should be an OverrideShell when the pointer is grabbed to prevent other win- 
dows from getting input while the popup is up, and the shell should be TransientShell for 
other popups. This is discussed further in Chapter 13, Menus, Gadgets, and Cascaded Pop- 
ups. 

Note that we are using the term resources here in a general sense, rather than implying its Xt-specific meaning. 
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The other additional subclass of Shell is topLevelShellWidgetClass, which is used to 
create additional, non-popup, top-level shells. Some applications have multiple permanent 
top-level windows. One of the top-level shells would be of the applicationShell- 
WidgetClass, and the rest would be of the topLevelShellWidgetClass. Each 
would have a separate icon. 

11.1.2 

Setting Shell Resources 

Shell resources are primarily a way for the user and the application to send in data to be com- 
municated to the window manager. These window manager hints control several major areas 
of window manager activity: they manage screen space, icons, and keyboard input. We'll 
discuss these areas one at a time in the following sections. Table 11-1 lists the Shell widget's 
resources with a brief description of what they control, and whether the application, the user, 
or Xt normally sets them. 

As indicated in Column 3 of the table, some Shell resources are intended to be set only once. 
These set-once resources can be left to their default values, set in the app-defaults file, or 
they can be set in the code before the Shell widget is realized; but they should not be set with 
XtSetValues ( ) after realization. 

Table 11-1. Shell Resources 

Resource 

Usually set by Xt or Shell itself, 
depending on the subclass: 
XtNargc 
XtNargv 
XtNoverrideRedirect 

Purpose 

Command-line args count 
Command-line args 
Set for pop-up shells not to be decorated 

When Settable 

XtNtransient 
XtNwaitForWm 
XtNwindowG roup 
XtNwmTimeout 
Usually set by user : 
XtNiconX 
XtNiconY 
XtNiconic 
XtNgeomet ry 
XtNtitle 
usually set by application : 
XtNallowShellResize 
XtNbaseHeight 
XtNbaseWidth 
XtNheightInc 
XtNwidthInc 
XtNiconMask 

Set for pop-up shells 
Whether to wait at all 
Links popups to main window 
Waiting time for slow wm 

Icon position 
Icon position 
Sets XtNinitialState to iconic 
Initial size and position 
String for title bar 

Does shell ask wm for size change? 
Height of fixed components 
Width of fixed components 
Desired height increment 
Desired width increment 
Mask used with icon pixmap 

Before realization 
Before realization 
Before realization 
Before realization 
Anytime 

Anytime 
Anytime 
Anytime 
Anytime 
Anytime 
Before realization 
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The Shell widget will continue without waiting for the event that would otherwise arrive 
to report the size of the window, and also without updating Xt's internal cache of window 
geometries. When this event does arrive later, Xt may set XtNwaitForWm back to 
True and update its internal cache. These resources should normally be left to their 
default values. 

The XtNgeometry and XtNiconic resources are intended to be specified by the user. 
Only these two resources use standard command-line options. The XtNgeometry resource 
is settable using a command-line option of the form: 
-geometry [ width{x}height ][ { +- }xposi tion{ + - }yposi tion ] 
(Either the size or position portion of the geometry string may be omitted, as indicated by the 
square brackets. In specifying the x or y position, a positive value, indicated by a plus sign, is 
relative to the top or left side of the reference window, while a negative value, indicated by a 
minus sign, is relative to the bottom or right side.) 
The -iconic command-line option, if present, sets the XtNiconic resource, indicating to 
the window manager that the application should start up as an icon. 
The XtNicon_x and XtNicon_y icon position hints are best left specified by the user. 
Icons' positions are determined by the window manager based on these hints or on an icon- 
positioning policy. An application with several top-level windows could set the icon position 
hints in its app-defaults file so that the icons for each top-level window appear side-by-side. 
We will discuss the remaining resources in related groups. Section 11.1.3 discusses the ones 
related to the size of the application's main window and other screen space issues. Section 
11.1.4 describes the keyboard input model hint. Section 11.1.5 describes how applications 
should handle colormaps to cooperate with the window manager. Section 11.1.6 describes 
the ones that apply to the application's icon. 

11.1.3 Screen Space 

The Shell widgets of each application have windows that are children of the root window. 
These are called top-level windows. The window manager directly controls the size and 
position of the top-level windows of each application. The window manager does not control 
the geometry of other widgets that are the descendants of the Shells, except indirectly 
through the geometry management mechanism described in Chapter 12, Geometry Manage- 
ment. 
The most basic size hint, the one that specifies simply the desired initial height and width, is 
automatically set by Xt based on the size of the child of the Shell widget. This hint is used 
by most window managers to display the outline of your application when it first appears on 
the screen, ready for the user to place and/or size the application. If your application does 
not have specific size needs, you need not set any additional resources. 
The additional size hints specify the application's range of desired sizes, desired increments 
of sizes, and desired range of aspect ratios. These are set by the XtNbaseHeight, 
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XtNbaseWidth, XtNminWidth, XtNminHeight, XtNmaxWidth, XtNmaxHeight, 
XtNwidthInc, XtNheightInc, XtNminAspectX, XtNminAspectY, XtNmax- 
AspectX, and XtNmaxAspectY sources. 

Size increment hints are useful for applications that prefer to be in units of a particular num- 
ber of pixels. Window managers that listen for this hint always resize the window to the base 
size (for each dimension), plus or minus an integral multiple of the size increment hint for 
that dimension. If the base size resource has not been set, the minimum size is used as the 
base. For example, xterm uses the font width and font height as width and height increment 
hints, because it prefers not to have partial characters or dead space around the edges. The 
bitmap editor application described in Chapter 4, An Example Application, should probably 
set both the width and height increments to the cell_size_in_pixels, since the bitmap 
cells are square. 

Most applications that use size increment hints redefine the interpretation of geometry speci- 
fications (the XtNgeometry resource, settable through the -georaetry standard 
command-line option) to reflect the size increments. For example, the width and height in 
xterm geometry specifications are in units of characters, not pixels. The Vtl00 widget within 
xterm implements this by having an XtNgeometry resource separate from the shell geome- 
try resource with that name. The entry for this resource in the widget resource list specifies 
the Vtl00 instance structure field, not the shell instance structure field. Then the reali ze 
method for the Vtl00 parses the geometry string with XParseGeometry() (an Xlib rou- 
tine that returns four separate variables containing the size and position from the geometry 
string) and sets the width and height fields of the core structure and the various size hints 
according to the returned variables. (The Vtl00 within xterm is not a real, self-sufficient 
widget. For one thing, it has no set_values method. For any real widget to implement 
this approach to interpreting geometry specifications, the set_values method would have 
to multiply the XtNwidth and XtNheight resource settings by the increment hints.) 

An aspect ratio is the ratio of the width to height measurement or vice versa. The XtNmin- 
AspectX and XtNminAspectY resources are used together to determine one extreme of 
acceptable aspect ratios, and XtNmaxAspectX and XtNrnaxAspectY determine the other 
extreme. For example, to suggest that the xmh application never be more than four times 
larger in one direction than it is in the other, the following values (as they would appear in 
the app-defaults file) would suffice: 
xmh* topLevel, minAspectX: i 
xmh*topLevel, minAspectY: 1 
xmh*topLevel, maxAspectX: 4 
xmh* topLevel, maxAspectY: 4 

Remember that every application must be able to do something reasonable given any size for 
its top-level window, even if the window is too small to be useful or if any of these hints are 
ignored by the window manager. 
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setting the keyboard focus to any of its windows. This type of client sets XtNinput to 
False. 

Note that even if the XtNinput resource is not set to True, your application will still work 
under some window managers, including uwrn, twrn, and rnwrn. This is because these win- 
dow managers use the pointer-following keyboard focus model or ignore this hint. However, 
it is not wise to assume that all window managers will ignore this hint. Therefore, if your 
application expects keyboard input, and is not of the globally active type described above, 
you can use the code shown in Example 11-1 to set the XtNinput resource. 

Example 11-1. Setting the XtNinput resource of a Shell widget 
main (argc, argv) 
int argc; 
char *argv[ ] ; 
{ 

/* create the Shell widget, setting resource */ 
topLevel = XtVaAppInitialize (&app_context, "Xmh", 
table, XtNumber (table), 
&argc, argv, NULL, 
XtNinput, (XtArgVal) True, 
NULL) ; 

} 
Note that the XtNinput resource should always be hardcoded, since the application may 
fail if the user is allowed to change the expected style of keyboard focus. 
For a further discussion of the keyboard focus, see Section 14.4. 

11.1.5 

Colormaps 

On most color systems, the display uses one or more hardware registers called colormaps to 
store the mapping between pixel values and actual colors, which are specified as relative 
intensities of red, green, and blue primaries (RGB values). 

X allows virtual colormaps to be created by applications. Some high-performance systems 
even allow all virtual colormaps to be installed in hardware colormaps and used at the same 
time, even to the level of one colormap per window. Far more commonly, though, there is 
only one hardware colormap, and virtual colormaps have to be copied into the hardware 
colormap one at a time as needed. Copying a virtual colormap into the hardware colormap is 
called installing the colormap, and the reverse process where the default colormap is 
installed is called uninstalling. The window manager is responsible for installing and unin- 
stalling colormaps. 
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The colormap window attribute of a window is an unchangeable characteristic of that win- 
dow, that is assigned when the window is created (when the widget is realized). The Core 
realize method sets it based on the XtNcolormap Core resource of the widget. There- 
fore, if a widget must have a certain colormap, you must set its XtNcolormap resource 
while creating the widget. Attempting to set XtNcolormap after a widget is created will 
have no effect on its colormap window attribute. 

11.1.6 

Icons 

The window manager always manages the icons for each application. Depending on the win- 
dow manager, these icons may simply contain a text string called the icon name, or they may 
contain a pattern that identifies the application, called the icon pixmap. The window man- 
ager is not obligated to display the application's icon pixmap (by default, mwm and twm do 
not display the icon pixmap). However, the window manager will always display at least the 
icon name. 

An application may supply an icon name by setting the XtNiconName resource; if it does 
not, the window manager will usually use the application name or the value of the XtN- 
t i t le resource. 

The application should supply the pattern for the icon, in the form of a single-plane pixmap, 
as the XtNiconPixmap resource. There are two basic ways to do this: one is by including 
bitmap data, and the other is by reading it in at run time. The former is easy to do with an 
Xlib call; the code that needs to be added is shown in Example 11-2. The latter technique, 
because it involves building a filename and looking in a number of locations for the file, is 
better done with a converter defined by the Xmu library. This converter technique is more 
complicated because the converter has to be registered and called with the proper arguments. 
The example using a converter is provided in the example source code for this book (xicon2), 
but is not shown here. See Chapter 10, Resource Management and Type Conversion, for 
more information on invoking converters. 

Example 11-2. Creating an icon pixmap, and setting XtNiconPixmap 

#include <Xll/Shell.h> 
#include "icon" 
main(argc, argv) 
int argc; 
char **argv; 
{ 
Pixmap iconpixmap; 

/* create topLevel here */ 
icon_pixmap = XCreateBitmapFrcmData(XtDisplay(topLevel), 
RootWindcOfScreen(XtScreen(topLevel)), 
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Examp 11-2. Creating an iconpixmap, andseing XtNiconPixmap (continued) 
icon_bits, 
iconwidth, icon_height ); 
XtVaSetValues(topLevel, XtNiconPixmap, icon_pixmap, NULL); 

/* realize widgets */ 
The included file, icon, is in standard X11 bitmap file format. You can create such a file 
using the bitmap application from the standard distribution, or xbitmap5 from the examples 
for this book. 
The window manager may have a preferred standard size for icons. If so, it will set a prop- 
erty. The application can read this property with the Xlib call XGetIconSizes (). To 
fully support a variety of window managers, an application should be capable of creating 
icon pixmaps of different sizes, depending on the values returned by XGetIconSi zes (). 
An application has the option of creating its own icon window, and then passing its ID to the 
window manager for management. This might be done so that the application can draw a 
multi-colored picture in the icon, instead of the traditional two-color bitmap, or animate the 
icon. However, as with all hints, the window manager is not guaranteed to honor your desires 
and may just ignore the icon window you provide. But if you want to try anyway, create the 
window using Xlib calls, and select input on it so that your application receives Expose 
events when they occur. Then set the ID of the window using the XtNiconWindow 
resource, before realizing the application. Then make sure your event loop redraws the icon 
when it receives Expose events on it. Accomplishing this will require writing your own 
modified version of XtAppMainLoop ( ) to handle the icon events. 

11.1.7 

Window Manager Decorations 

Virtually all current window managers decorate windows on the screen.% These decorations 
typically include a title bar for the window with gizmos for moving and resizing the window. 
Current decorating window managers include twm, awm, mwm, olwm, and gwm. 

The way these decorations are implemented can have an impact on Toolkit applications. The 
window manager places the decorations in a window slightly bigger than the application, and 
then reparents the application's top-level window into the decoration window. Reparenting 
gives the top-level window a new parent instead of the root window. The window manager 
actually creates the frame window as a child of the root window, then reparents the applica- 
tion's top-level window into the frame, and then maps the frame window. 

Reparenting affects the application mainly when you try to determine a global position (rela- 
tive to the root window) from the XtNx and XtNy resources of the Shell widget. This is 
usually done in order to place popups. Under a nonreparenting window manager such as 

#The uwm window manager doesn't decorate, but it is defunct as of R4 since it doesn't honor the current ICCCM. 
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uwm, these coordinates are indeed relative to the root window, because the parent of the shell 
is the root window. However, under a window manager that reparents, the coordinates of the 
application's main Shell widget are relative to the decoration window, not the root window. 
Therefore, these coordinates cannot be used for placing popups within the application. 
Motif's internal code that places a popup uses XtTranslateCoords ( ) instead of relying 
on the position resources. 

11.1.8 

Interacting with the Window Manager 

The application and the window manager can communicate back and forth through proper- 
ties stored on the server. The properties are associated with the top-level window of your 
application, so unlike selections, similar communications can be going on at the same time 
between different clients and the window manager without interference. The ICCCM, Inter- 
Client Communication Conventions Manual, defines a starting point for what information 
can be sent back and forth.t 
All Shell widgets handle the required communication with the window manager; this section 
concerns optional communication. Note that applications should not depend on this type of 
communication. An application may run under a different window manager that doesn't lis- 
ten to this type of message. Furthermore, an application is not required to use this type of 
communication, because mwm runs fine without it. This type of communication is just icing 
on the cake. 
The next section describes the protocol group defined by the ICCCM. You must include the 
header file <Xll/Protocols.h> to use any of these features. 
Before you can use these features, you must also prepare the required atoms. The type Atora 
is an ID for the string name for a property. All applications know the name of the property 
they will use for communication (such as WM_PROTOCOLS), but they don't know the ID for 
it since it changes each time the server is run. You can get the Atom for a property name by 
calling XInternAtom ( ) or using Xmu's atom caching facility. This is called interning the 
atom. All the fully capitalized words used in this section are property names, and must be 
interned before use. 
You indicate interest in participating in one or more of them by setting the WM_PROTOCOLS 
property on a window using a value which is the list of the atoms for the protocols you want 
to receive for that window. Then you watch for ClientMessage events containing these 
protocol atoms in the data field. Of course, it is possible to resign from any of the protocols 
whenever you want by repeating the above process. 

"l'The ICCCM is reprinted as an appendix of Volume Zero, X Protocol Reference Manual. 
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11.1.8.1 WM PROTOCOLS 

The WM_PROTOCOLS are messages sent to your application from the window manager that 
notify you of conditions requiring immediate action. There are currently three protocols 
defined in the ICCCM, but the list may expand. 
WM_DELETE_WINDOW indicates that the user has just requested that one of your applica- 
tion's windows be destroyed. Your application should respond by destroying that window if 
possible without exiting. The idea behind this protocol is that some applications have multi- 
ple top-level windows, and if the window manager were simply to delete one without the 
application's cooperation, the application might not be able to recover. (You should partici- 
pate in this protocol if you have multiple top-level windows.) 
WM_SAVE_YOURSELF indicates that the user has just requested that your application be 
killed. You should save all data immediately in preparation. This should execute code 
equivalent to the code you have implemented for your application's quit feature, except that 
it does everything except exit. (You should participate in this protocol if you have data that 
could be lost by exiting abnormally.) 
WM_TAKE_FOCUS indicates that your application has been given the keyboard focus. You 
would participate in this protocol if you wanted the keyboard focus to always start in one of 
your subwindows, instead of your main window. 

11.2 Selections: Widget-to-Widget Communication 

Selections are a general mechanism for communicating information between two clients of 
the same server. The most familiar example of selections is selecting text from one xterm 
application and pasting it into another. This text can also be pasted into an xmh mail compo- 
sition window, or into an xedit application. 

In Xt applications, selection is normally implemented within widgets. For example, the 
Athena Text widget is used by xmh and xedit, and it is this widget that supports cutting and 
pasting of text in these applications. The application code of xmh and xedit does not play a 
part in the communication of selection data. The fact that selection is implemented in widg- 
ets also means that two widgets within the same application can communicate with each 
other through selections. For example, the Text widget is sometimes used to provide single- 
line input fields in an application. Since the Text widget supports selections, the user could 
select the text in one field and paste it into another field. This feature would be present with- 
out any code in the application. If the same widget class supports both copying and pasting, 
selections can be used to move data in a single widget. For example, selections allow you to 
copy text within an editor in xterm and paste the text in a new place (although some editors 
require keyboard commands to position the insertion point). 

The selection mechanism is not limited to text. It requires only that the sender and recipient 
have knowledge of the format of the data being transferred. Therefore, selections can be 
used to transfer graphics between widgets that can understand a common format for com- 
municating graphics. Unfortunately, a standard format for graphics selections has not yet 
been agreed upon. 
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The selection mechanism uses properties for transferring data and uses the Selection- 
Clear, SelectionNotify, and SelectionRequest event types to synchronize the 
communication. Essentially, a property is common storage. Properties are stored in the 
server, and are named pieces of data associated with a window on that particular server, that 
any client of that server can read or write. Because the various clients may not be running on 
the same host, all communication between applications and between applications and the 
window manager must take place through the server using properties.t" 

The basic routines used to implement selections are part of Xlib. Xt provides an interface to 
the Xlib selection routines that makes selections easier to use in the context of widget code. 
Since there is a maximum size for the data stored in a single property, communication of 
large blocks of data using Xlib requires several partial transfers. Xt supplies routines that 
transparently perform the multiple partial transfers so that they appear to the application pro- 
gram like a single transfer, called an atomic transfer. 

Xt also supplies a separate set of parallel routines that transfer a large selection one chunk at 
a time so that it appears as multiple small selections. This is called an incremental transfer. 
Incremental transfer can be preferable on systems with limited memory and more natural 
when the data is normally stored in small chunks. 

The Toolkit selection routines also have built-in timeouts, so that one application won't wait 
forever for another to provide data. 

First we'll give you an overview of how an atomic selection transaction works, and then 
we'll discuss and demonstrate how to write the code to implement atomic selections in a 
widget. Following this is a discussion of how incremental selections work, and finally a dis- 
cussion of the standard selection formats (known as target types). 
If you are writing a custom widget that contains data that could be pasted into other instances 
of the widget or other widgets, you should read on to see how to implement selections. 
Otherwise, the rest of this chapter is probably only of academic interest to you. 

11.2.1 

How Atomic Selection Works 

Selections communicate between an owner widget and a requestor widget.$ The owner has 
the data and the requestor wants it. The owner is the widget in which the user has selected 
something, and the requestor is the widget in which the user has clicked to paste that some- 
thing. Many widgets need to act as both owner and requester at different times. The code to 
handle each of the two roles is separate. 

-t It is not practical to write your own networking routines in an application to communicate with other clients running 
on different hosts because your client may be communicating with the server using TCP/IP, and the other client may 
be using DECnet. Both may be the same X application that you wrote, but compiled with a version of Xlib that uses 
a different protocol layer underneath the X Protocol. When you communicate through the server using properties, 
the server takes care of the translation. 
t Note that since selections can be implemented in the application, as they are by non-Xt applications, the words "ap- 
plication" and "'widget" are interchangeable in this section. 
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Example 11-3. BitmapEdit: actions that highlight selection (continued) 

-Shi ft<Btn2Down>: UndoCell ( ) \n\ 
-Shi ft<Btn3Down>: ToggleCell ( ) \n\ 
-Shift<BtnlMotion>: DoCell ( ) \n\ 
-Shift<Btn2Motion>: UndoCell ( ) \n\ 
-Shift<Btn3Motion>: ToggleCell ( ) "; 

static XtActionsRec actions [ ] = { 
{ "DoCell", DoCell}, 
{ "UndoCell", UndoCell }, 
{"ToggleCell", ToggleCell}, 
{ "StartHighlight" , StartHighlight }, 
{ "ExtendHighlight", ExtendHighlight }, 
{ "MakeSelection", MakeSelection}, 
{ "PasteSelection", PasteSelection}, 

* User presses first button (by default), starting highlighting. 
*/ 
static void 
StartHighlight (w, event) 
Widget w; 
XButtonEvent *event; 
{ 
BitmapEditWidget cw = (BitmapEditWidget) w; 
cw->bitmapEdit, first_box = False; 
cw->bitmapEdit, select_start_x = (cw->bitmapEdit. cur_x + event->x) 
/ cw->bitmapEdit, cell_size_in_pixels; 
cw->bitmapEdit.select_start_y = (cw->bitmapEdit.cur_y + event->y) 
/ cw->bitmapEdit, cell_size_in_pixels; 
/* clear old selection */ 
Redisplay(cw, NULL) ; 
} 
/* 
* MakeSelection is call when the first button is released (by 
* default). This finishes the user's highlighting, and means 
* triggers ownership of the PRIMARY selection. 
*/ 
static void 
MakeSelection (w, event) 
Widget w; 
XButtonEvent *event; 
{ 
BitmapEditWidget cw = (BitmapEditWidget) w; 
int temp; 
cw->bitmapEdit.select_end_x = (cw->bitmapEdit.cur_x + event->x) 
/ cw->bitmapEdit, cell_size_in_pixels; 
cw->bitmapEdit.select_end__v = (cw->bitmapEdit.cttr_y + event->y) 
/ cw->bitmapEdit.cell_size_in_pixels; 
if ( (cw->bitmapEdit .select_end_x == cw->bitmapEdit.select_start_x) 
&& (cw->bitmapEdit. select_end_y == 
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Example 11-3. BitmapEdit: actions that highlight selection (continued) 

cw->bitmapEdit, select_start_y) ) 
Redisplay (cw, NULL) ; 
return; /* no selection */ 

/* swap start and end if end is greater than start */ 
if (cw->bitmapEdit.select_end_x < cw->bitmapEdit.select_start_x) { 
temp = cw->bitmapEdit.select_end_x; 
cw->bitmapEdit, select_end_x = cw->bitmapEdit, select_start_x; 
cw->bitmapEdit.select_start_x = temp; 
} 

if (cw->bitmapEdit. select_end_y 
< cw->bitmapEdit, select_start_y) { 
temp = cw->bitmapEdit, select_end_y; 
cw->bitmapEdit, select_end_y = 
cw- >bitmapEdit. select_start_y; 
cw->bitmapEdit.select_start__v = temp; 
} 

if (XtOwnSelection(cw, XA_PRIMARY, event->time, convert_proc, 
lose_ownership_proc, transfer_done_proc) == 
False) { 
XtWarning( "bitmapEdit: failed attempting to become 
selection owner; make a new selection. \n"); 
/* Clear old selection, because lose_ownership_proc 
* isn't registered. */ 
Redisplay (cw, NULL) ; 
} 

* 
* ExtendHighlight is called when the mouse is being dragged with 
* the first button down (by default). During this time, the 
* bitmap cells that are selected (by crosses) are dynamically 
* changed as the mouse moves. 
*/ 
static void 
ExtendHighlight (w, event) 
Widget w; 
XMotionEvent *event; 
{ 
BitmapEditWidget cw = (BitmapEditWidget) w; 
static int last_drawn_x, last_drawn_y; 
int event_cell_x, event_cell__v; 

event_cell_x = cw->bitmapEdit.cur_x + (event->x / 
cw->bitmapEdit, cell_size_i_pixels) ; 
event_cell_y = cw->bitmapEdit.cum__v + (event->y / 
cw->bitmapEdit, cell_size_i_pixels) ; 
if ((event_cell_x == last_drawn_x) && (event_cell__v == 
last_drawn_y) ) 
return; 

if (cw->bitmapEdit. first_box) { 
DrawBoxOfXs(cw, last_drawn_x, last_drawn_y, False); 
DrawBoxOfXs(cw, event_cell_x, event_cell_y, True); 
} 
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Example 11-3. BitmapEdit: actions that highlight selection (continued) 

else { 
DrawBoxOfXs(cw, event_cell_x, event_cell_.v, True); 
cw->bitmapEdit.first_box = True; 
} 

last_drawn_x = event_cell_x; 
last_drawn_y = event_cell_y; 

DrawBoxOfXs fills a rectangular set of bitmap cells with 
crosses, or erases them. 

static void 
DrawBoxOfXs(w, x, y, draw) 
Widget w; 
Position x, y; 
Bool draw; 
{ 
BitmapEditWidget cw = (BitmapEditWidget) w; 
Position start_pos_x, start_pos_y; 
Dimension width, height; 
GC gc; 
int i, j ; 
start_pos_x = cw->bitmapEdit.cur_x + 
cw- >bitmapEdit. select_start_x; 
start_pos_y = cw->bitmapEdit.cur_x + 
cw->bitmapEdit, select_start_y; 
/* swap start and end if end is greater than start */ 
if (x < start_pos_x) { 
width = start_pos_x- x; 
start_pos_x = x; 
} 
else { 
width = x - start_pos_x; 
} 
if (y < start_pos_y) { 
height = start_pos_y - y; 
start_pos_y = y; 
} 
else { 
height = y - start_pos_y; 
} 
for (i=start_pos_x;i < start_pos_x + width;i++) 
for (j=start_pos_y;j < start_pos_y + height;j++) 
DrawX (cw, i, j, draw) ; 
} 
/* 
* DrawX draws an X in a bitmap cell, in white if a black cell, and 
* in black if a white cell. 
*/ 
DrawX(cw, x, y, draw) 
BitmapEditWidget cw; 
Position x, y; 
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Code was added to the initialize method to create this latter GC. (See the example 
code distribution for this modified widget instance structure.) 
The MakeSelection action is triggered when the button is released after dragging, indi- 
cating that the selection is complete. This action sets the select_end._x and 
select_end_y instance part variables to reflect the bottom-right corner of the selection, 
and then swaps the top-left and bottom-right coordinates if the end coordinate is to the left or 
above the start coordinate. If the start and end coordinates are the same, then the action 
returns, since no selection was made. If a selection was made, MakeSelection calls Xt- 
OwnSelection (). 

11.2.3 

Making the Selection with XtOwnSelection (Owner) 

Once the area is highlighted, Widget A calls XtOwnSelection () to assert that it wants 
the right to set the value of a property that will be used to transfer information. 
XtOwnSelection ( ) is called with six arguments: 
Boolean XtOwnSelection(widget, selection, time, convert_proc, 
1 ose_ownership_proc, transfer_done_proc) 
Widget widget; 
Atom selection; 
Time time; 
XtConver t Select ionProc convert_proc; 
XtLoseSelectionProc lose_owner ship_proc; 
XtSelect ionDoneProc trans fer_done_proc; 
The selection argument specifies an Atom--a number representing a property. Proper- 
ties are arbitrarily named pieces of data stored on the server. To simplify communication 
with the server, a property is never referenced by name, but by a unique integer ID called an 
atom. Standard atoms are defined in <Xatom.h> using defined symbols beginning with XA_; 
nonstandard atoms can be obtained from the server by calling the Xlib function XtIntern- 
Atom. 
Widgets that support one selection at a time pass the predefined XA_PRIMARY atom to Xt- 
OwnSelection ( ). The ICCCM also allows you to use the XA_SECONDARY and XA_CLIP- 
BOARD atoms. XA_SECONDARY would be used by widgets implementing behavior involving 
more than one selection (for example, allowing the user to make two selections, and to 
exchange the data they contain). No current clients implement this behavior. The XA_CLTP- 
BOARD atom should be used by a widget that allows the user to delete a selection. We'll talk 
more about the properties referenced by the XA_SECONDARY and XA._CLIPBOARD atoms in 
Section 11.3. 
The purpose of the XtOwnSelection ( ) call is to make sure that only one widget has the 
right to set the XA_PRTMARY selection property at a time, and to assert that this widget is pre- 
pared to honor requests for this data. Notice that when you select text with xterm, that text is 
highlighted only until you select a different area in a different window. 
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11.2.4.1 

XtPointer client_data; 
Time time; 
The selection argument is an atom specifying which property is being used to transfer 
the selection. This will typically be XA_PRIMARY, though in theory two widgets (or two 
instances of the same widget) could agree to transfer some particular data using other proper- 
ties. 
The target argument is another atom, this one specifying a target representation type in 
which the requestor wants the information. We'll talk more about the possible values for this 
atom in a moment. 
The callback argument is a pointer to a callback procedure that actually pastes the data. 
Xt will call this procedure when the owner has converted the data. The XtGet- 
SelectionValue() call registers the callback with Xt, and sends a Selection- 
Request event to the owner. 
When the selection owner has successfully converted the data, the owner sends back a 
Selection_Notify event to Xt. Xt then calls the requestor's callback procedure. The 
callback procedure must handle the pasting of the data into the widget's data structures, and 
it must handle the case where the data could not be converted into the requested representa- 
tion. We'll discuss the responsibilities of this procedure in more detail once we've seen the 
owner's conversion procedure. 
The client_data argument of XGetSelectionValue ( ) is normally used to pass the 
event that triggered the pasting into the requestor callback. The callback will use the coordi- 
nates at which the event occurred as the location at which to paste the data. 
As in the call to XtOwnSelection ( ), the time argument should be the time from the 
event that initiated the pasting, not the constant CurrentTime. 

Possible Target Type Atoms 

The target argument to XtGetSelectionValue () is an atom that the requestor uses 
to tell the owner what kind of information it is looking for from the selection.% This is not 
necessarily a conversion of the actual selection data. For example, it might be a timestamp 
on the data, or some characteristic of it, such as its size or font. 
To take full advantage of the Xt selection mechanism, you need to understand what atoms 
can be used as selection targets. However, apart from some standard, predefined atoms, the 
atom for a property is not known by a client until it queries the server for the atom using an 
XInternAtom ( ) call. This call specifies the string name of the property and returns the 
atom. 
The header file <Xll/Xatom.h> contains some predefined atoms that are needed by almost all 
application. These atoms are symbolic constants that can be used without an XIntern- 
Atom ( ) call. The constants always start with the prefix XA_. See <Xll/Xatom.h> for the 
complete list of predefined atoms. 

-t As described earlier, atoms (rather than strings) are always used in network transmissions to identify properties. 
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11.2.4.2 

The third argument to XInternAtom ( ) is a Boolean that indicates what to do if the atom 
doesn't already exist. If this argument is True, XInternAtom ( ) will return None if no 
other client has already initialized this atom. This argument should always be False since 
your widget might be the first to try to make a selection using this target type atom. In a 
Motif application, one could use XmInternAtom ( ) instead of XInternAtom (). 

Note that for repeated calls to XInternAtom ( ) with the same string as an argument, even 
from different widgets or from a different application, the returned atom will be the same. 
There will be only one atom created for any unique string interned on a given server. (Case 
is important: "Cell_Array" would return a different atom than "CELL_ARRAY".) 

This XInternAtom() call occurs in every instance of the BitmapEdit widget, since all 
instances need to know the atom to participate in selections using that target type. 

The Paste Action from BitmapEdit 

To initiate the requestor role, you need to assign an event sequence to trigger the pasting, 
write an action that calls XtGetSelectionValue ( ), and write a callback function that 
inserts the returned data. 

Traditionally, the action to paste data is triggered by a press of the second pointer button. 
BitmapEdit will use the shifted second button since it uses the unshifted button for other pur- 
poses. Example 11-5 shows the action mapped to Shift<Btn2Down>. 

Example 11-5. BitmapEdit: action to paste a selection 
static void 
PasteSelection (w, event) 
Widget w; 
XButtonEvent *event; 
{ 
BitmapEditWidget cw = (BitmapEditwidget) w; 
XtGetSelectionValue(cw, XA_PRIMARY, cw->bitmapEdit.target_aton, 
requestor_callback, event, 
event->time) ; 
This action can be dropped verbatim into your widget, replacing only the widget name and 
the name of the instance fields you are using to store the target atom. 

11.2.5 

Converting the Selection (Owner) 

The real challenge in handling selections is writing the convert_proc, which converts 
data to the format specified by the requestor and prepares it for transfer. 

As mentioned above, the widget's convert_proc is called by Xt when the requestor calls 
XtGetSelectionValue (). The procedure is passed the selection atom and the target 
atom, and is expected to retum in its arguments the type, value, size, and format of the con- 
vened selection data. 
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Example 11-6. BitmapEdit: converting the selection value (continued) 
/* Required atom: see Example ii-i0 */ 

} 
else if (*target == cw->bitmapEdit.target_atom) { 
char *data; 

width = cw->bitmapEdit.select_end_x - 
cw->bitmapEdit, select_start_; 
height = cw->bitmapEdit, select_end_y - 
cw- >bitmapEdit. select_startv; 

/* 8 chars is enough for two 3-digit 
* numbers and two delimiters */ 
*length_return = ((width * height) + 8) * sizeof(char); 

data = XtMalloc (*length_return) ; 

sprintf(data, "%d@%d-", width, height); 

for (x = 0; x < width; x++) { 
for (y = 0; y < height; y++) { 
data[8 + x + (y * width)] = cw->bitmapEdit.cell[(x + 
cw->bitmapEdit.select_startx) + 
((y + cw->bitmapEdit.select_startv) * 
cw->bitmapEdit.pixmap_width in 9ells)]; 
} 
} 

*value_return = data; 

*type_return = cw->bitmapEdit, target_atom; 

*format_return = 8; /* number of bits in char */ 
return(True); 
} 
else { 
/* code to handle standard selections: see Example 11-10 */ 

} 
} 
This code determines the width and height of the selected rectangle from the instance part 
fields, and then allocates enough memory to fit a character array big enough to fit the width 
and height values, delimiters, and a width by height character array. Then it copies the cur- 
rent contents of the selected area into the allocated character array. Finally, it sets 
*value_return to point to the compound string, and sets *length_return to the 
length of this string. * format_return is the size in bits of each element in the array, 
which in this case is 8 bits. 
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11.2.6 Finally Pasting the Selection (Requestor) 

When the owner's convert_proc returns, Xt sends a SelectionNotify event to the 
requestor. The Xt code on the requestor side then invokes the callback routine the requestor 
registered with the call to XtGetSelectionValue (). 
The requestor_callback function is passed all the same arguments that the owner 
received in the convert_proc, plus the values that the owner returned through the argu- 
ment of convert_proc. In the BitmapEdit widget, it sets instance part fields to paste the 
data. 
Example 11-7 shows the requestor callback function from BitmapEdit. 

Example 11-7. BitmapEdit: pasting selection in requestor_callback function 
I* ARGSUSED *I 
static void 
requestor_callback (w, client_data, selection, type, value, length, format) 

Widget w; 
XtPointer client_data; 
Atom *selection; 
Atom *type; 
XtPointer value; 
unsigned long *length; 
int *format; 
{ 

/* cast to XButtonEvent below */ 

BitmapEditWidget cw= (BitmapEditWidget) w; 
if ((*value := NULL) && (*length == 0)) { 
XBell(XtDisplay (cw), i00); 
XtWarning("bitmapEdit: no selection or selection timed out:\ 
try again\n"); 
} 
else { 
XButtonEvent *event = (XButtonEvent *) client_data; 
int width, height; 
int x, y; 
int dst_offset_x, dst_offset_y; 
char *ptr; 

dst_offset_x = (cw->bitmapEdit.cur_x + event->x) / 
cw->bitmapEdit.cell_size_in_pixels; 
dst_offset_y = (cw->bitmapEdit.cur_y + event->y) / 
cw->bitmapEdit.cell_size_in_pixels; 

printf("dst offset is %d, %d\n", dst_offset_x, dst_offset_y); 

ptr = (char *) value; 
width = atoi (ptr) ; 
ptr = index(ptr, '@'); 
ptr++; 
height = atoi (ptr); 
ptr = &value[8]; 

for (x = 0; x < width; x++) { 
for (y = 0; y < height; y++) { 
/* range checking */ 
if (((dst_offset_x + x) > 
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11.2.7 If the Selection Is Lost (Owner) 

If the owner loses the selection, either because the selection timed out or because the user 
made a different selection, the 2ose_ownership_proc that was registered with its call to 
XtOwnSelection ( ) will be invoked. Typically, this function simply clears any highlight- 
ing or other visual feedback about the selection, and resets to their initial state any internal 
variables used in handling selections. 

Example 11-8 shows the l ose_ownership_proc from the BitmapEdit widget. 

Example 11-8. BitmapEdit: the Iose_ownership_proc 
/* ARGSUSED */ 
static void 
lose_ownership_proc (w, selection) 
Widget w; 
Atom *selection; 
{ 
BitmapEditWidget cw = (BitmapEditWidget) w; 

/* clear old selection */ 
cw->bitmapEdit.first_box = False; 
cw->bitmapEdit.select_start_x = 0; 
cw->bitmapEdit.select_start_y = 0; 
cw->bitmapEdit, select_enc_x = 0; 
cw->bitmapEdit, select_end_ff = 0; 
Redisplay (cw, NLU/) ; 

11.2.8 When the Selection Transfer Is Complete (Owner) 

The transfer_done_proc, registered in the call to XtOwnSelection(), is called 
when the transfer is complete. Its job is to do any processing necessary to get ready for the 
next selection request. In many cases no processing is necessary and this function can be 
NULL in the call to XtOwnSelection (). However, this function might clear variables or 
free memory. Some transfers are intended to be made only once to make sure that there is no 
duplication of information. In these cases, the transfer_done_proc would do a lot 
more, including erasing the visual selection, calling XtDisownSelection() (and per- 
haps even erasing the data that was selected). 

11.2.9 

ICCCM Compliance 

For any two widgets to be able to transparently transfer different types of data, there must be 
agreement about the possible target types and their contents. The ICCCM suggests a list of 
possible target types, as shown in Table 11-2. If you can, use one of these target types since 
this will increase the chances that your widget will be able to communicate with widgets 
written by other people. 
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Table 11-2. Target Types Suggested in ICCCM 

Atom 

TARGETS 
MULTIPLE 
TIMESTAMP 
STRING 
TEXT 
LIST_LENGTH 
PIXMAP 
DRAWABLE 
BITMAP 
FOREGROUND 
BACKGROUND 
COLORMAP 
ODIF 
OWNER_OS 
FILE NAME 
_ 
HOST_NAME 
CHARACTER_POSITION 
LINE_NUMBER 
COLUMN_NUMBER 
LENGTH 
USER 
PROCEDURE 
MODULE 
PROCESS 
TASK 
CLASS 
NAME 
CLIENT_WINDOW 
DELETE 
INSERT_SELECTION 
INSERT_PROPERTY 

Type 

ATOM 
ATOM_PAIR 
INTEGER 
STRING 
TEXT 
INTEGER 
DRAWABLE 
DRAWABLE 
BITMAP 
PIXEL 
PIXEL 
COLORMAP 
TEXT 
TEXT 
TEXT 
TEXT 
SPAN 
SPAN 
SPAN 
INTEGER 
TEXT 
TEXT 
TEXT 
INTEGER, TEXT 
INTEGER, TEXT 
TEXT 
TEXT 
WINDOW 
NULL 
NULL 
NULL 

Meaning 

List of valid target atoms 
Look in the ConvertSelection property 
Timestamp used to acquire selection 
ISO Latin 1 (+TAB+NEWLINE) text 
Text in owner's encoding 
Number of disjoint parts of selection 
Pixmap ID 
Drawable ID 
Bitmap ID 
Pixel value 
Pixel value 
Colormap ID 
ISO Office Document Interchange Format 
Operating system of owner 
Full path name of a file 
See WM_CLIENT_MACHINE 
Start and end of selection in bytes 
Start and end line numbers 
Start and end column numbers 
Number of bytes in selection 
Name of user running owner 
Name of selected procedure 
Name of selected module 
Process ID of owner 
Task ID of owner 
Class of owner--see WM_CLASS 
Name of owner--see WM_NAME 
Top-level window of owner 
True if owner deleted selection 
Insert specified selection 
Insert specified property 

Because not every widget will support every possible target type, the ICCCM specifies a tar- 
get type of XA_TARGETS, to which the owner is required to respond by returning a list of the 
target types into which it is capable of converting data. 

Normally, a requestor would first call XtGetSelectionValue ( ) for XA_TARGETS, and 
then in the callback determine which target it wants to request from the list, and then call 
XtGetSelectionValue () again for the desired target with a separate callback to pro- 
cess the actual data. This is really two separate selection transfers. 
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11.2.9.1 

XA_TARGETS is not a predefined atom.% To use it, you must use the Xmu atom caching mech- 
anism described in Section 11.2.9.1. 
Fortunately, there is existing template code that you can copy to handle XA_TARGETS and 
some other standard target types that are required by the ICCCM. 
This template code uses the Xmu routine XmuConvertStandardSelection (). It also 
uses an Xmu atom-caching facility that eliminates the need for you to make Xlntern- 
Atom ( ) calls for each of the ICCCM standard target atoms. 

Xmu Atom Caching 

Xmu's caching facility uses symbols similar to those defined in <Xll/Xatom.h>, except that 
in this case they are macros that take an argument and call XmulnternAtom. For example, 
the macro for XA_TARGETS is defined as follows in <Xll/Xmu.h>: 
#define XA_TARGETS (d) XmulnternAtn(d, _XA_TARGETS) 
where d refers to a pointer to a Display structure. (This can be returned by the Xt- 
Display () macro.) The XmulnternAtom function first tries to get the atom for the 
string "XA_TARGETS'" from Xmu's internal cache. If Xmu doesn't yet have a value for the 
atom, it calls XlnternAtom( ) to make a server request. Because this facility makes only 
one query to the server, you can access the atoms in this way every time a selection is made 
without significant penalty. This allows you to place the XA_TARGETS () macro in your 
selection code instead of adding an instance part variable and setting it in the initialize 
method. 
You might use this macro as follows in a convert_proc branch dedicated to handling the 
TARGETS target type: 
if (*target == XA_TARGETS (XtDisplay (w)) ) { ... 
The Xmu atom caching mechanism must be initialized before you can make calls of the form 
just shown. Example 11-9 shows the code that should be placed in the widget's initial- 
ize method to initialize this mechanism. 

Example 11-9. BitmapEdit: initializing Xmu's atom caching mechanism in the initialize method 
(void) XmuInternAtn( XtDisplay (new), XmuMakeAtn( "NULL" ) ) ; 

%The X Protocol defines all the predefined atoms. Therefore, even though XA_TARGETS would be convenient to 
have as a predefined atom, this would change the protocol (albeit in a minor way). And the protocol is unlikely to be 
changed in even minor ways when there are workarounds, as in this case, because of the need for backwards compat- 
ibility. 
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Example 11-10. BitmapEdit: converting standard targets in the convert_proc (continued) 

} 
else { 
if (XmuConvertStandardSelection(cw, CurrentTime, selection, 
target, type_return, value_return, 
length_return, format_return) ) 
return True; 

else { 
XtWarning("bitmapEdit: requestor is requesting\ 
unsupported selection target type.\n"); 
return(False); 

} 
} 
} 

Overall, this code handles the TARGETS atom in the first branch, the normal selection target 
in the second, and any remaining standard atoms and any unknown atoms as two cases in the 
third branch. For ICCCM-compliant code, you can copy this entire function into your widget 
and then write just the second branch. Note that branches that successfully provide the 
requested data return True, and branches that don't return Fal se.% 
In the first branch you will also need to change the reference to the instance part field that 
stores the target atom used for selections, bitmapEdit, target_atom. If your widget 
uses a predefined atom or one supported by the Xmu facility, you would reference that atom 
here instead of the instance part field. If you called XInternAtom ( ) in initialize and 
stored the result in an instance part field, you specify that here. 
Note that XtGetSelectionRequest ( ) is used to get the time from the Selection- 
Request event that the owner received before Xt called the convert_proc function. 
XtGetSelectionRequest ( ) was introduced in R4 for this specific reason; it needs to 
meet the current ICCCM and work around the fact that the conver_.proc is defined with- 
out an event argument. (The conver._proc definition could not be changed because of 
the required backwards compatibility with R3.) 

11.2.10 

How Incremental Selection Works 

An incremental selection is very similar to an atomic transfer, except that you use different 
set of routines and procedure types, and Xt calls the procedures you register multiple times 
instead of just once as in atomic transfers. Incremental transfers and atomic transfers are 
mutually exclusive--an owner can support both, but if the owner doesn't, a requestor cannot 
use the incremental routines to request a selection owned atomically, or vice versa. 

"l-The ICCCM also specifies that functions implementing selections must be able to respond to a MULTIPLE target val- 
ue, which is used to handle selections too large to fit into a single property. However, the necessary handling is done 
by the Intrinsics. Your procedures do not need to worry about responding to the MULTIPLE target value; a selection 
request with this target type will be transparently transformed into a series of smaller transfers. 
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Calls of the lose_ownership_proc do not indicate completion of in-progress 
transfers--these transfers should continue. It just means that the owner lost ownership of the 
selection, so that the owner should unhighlight what the user selected. 

If transfer_done_proc is specified, the owner allocates and frees storage. If 
transfer_done_proc is NULL, convert_proc must allocate storage using Xt- 
Malloc (), XtCalloc ( ) or XtRealloc (), but Xt will free that memory. The owner 
may use XtDisownSelection ( ) to relinquish ownership. (This is the same routine used 
to relinquish ownership of an atomic selection.) 

11.2.11 

Miscellaneous Selection Routines 

If the user deletes the information selected, the owner should call XtDisown- 
Selection (). XtSetSelectionTimeout ( ) sets the time in which widgets must re- 
spond to one another. This is initially set by the XtNselectionTimeout resource, and 
defaults to 5 seconds. The selection timeout prevents hanging when the user pastes but the 
current owner is slow or hung. XtGetSelectionTimeout ( ) reads the current selection 
timeout value. Widgets should not normally require these two calls, since the selection 
timeout should remain under the user's control. 
If the requestor can request more than one target type, such as TARGETS and its normal selec- 
tion target, it normally does so using separate actions. (Both actions can be invoked by the 
same triggering event, if desired.) Each action specifies a different target type and a different 
requestor callback. That way, each requestor callback handles only one type of target. 
Beware: there is a danger in this approach. The selection owner might change between the 
repeated XtGetSelectionValue ( ) calls. XtGetSelectionValues ( ) (plural) can 
be used instead if the requestor would like to receive the data in more than one representa- 
tion. The requestor's single callback function would then be called once for each representa- 
tion. (The owner's convert_proc would also be called once per representation.) 

11.3 The Clipboard 

You've seen that Xt provides an underlying mechanism called selections that can transfer 
data from one widget instance to another, whether or not the instances are in the same appli- 
cation. The communication occurs through the server, using properties. Most widgets that 
display text already support selections. 

You can also use selections in your application code to transfer data to other instances of 
your application or to or from any other widget or application that understands the format of 
the data. However, selections are quite cumbersome to implement. 

Selections can also be used to place data on a special selection called CLIPBOARD. Like all 
selections, the CLIPBOARD selection is actually a property stored in the server, so that any 
client can read or write it. The clipboard can only hold one piece of data at a time. 
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Passing a large amount of data can take a few seconds. Therefore, the clipboard is set up so 
that the application does not actually pass data to the clipboard until the data has been re- 
quested by some other application or widget. Your application makes data available by reg- 
istering a function that supplies the data, and Xt calls that function when the data is request- 
ed. Thus if there is any delay in sending the data, it occurs when the data is pasted, not when 
it is cut. 
According to the ICCCM, if a widget or application allows the user to delete a selection, the 
selection owner code should place the deleted data on the CLIPBOARD selection. Since the 
CLIPBOARD selection is a list of selections, the most recent deletion should be pushed onto 
the stack of existing selections. 
The standard X distribution includes a special client, xclipboard, that shows the current value 
of the CLIPBOARD property, and allows it to be manipulated. Except when a widget asserts 
ownership of the CLIPBOARD with XtOwnSelection ( ) in order to place newly deleted 
data on it, the xclipboard client is the owner of this property. When it starts up, xclipboard 
asserts ownership of the CLIPBOARD selection. If it loses the selection (which will happen 
whenever a widget or client has newly deleted the contents of a selection), it obtains the con- 
tents of the selection from the new owner, then reasserts its own ownership of the selection. 
Clients wishing to restore deleted data should request the contents of the CLIPBOARD, using 
the same techniques as we've shown for the PRIMARY selection, xclipboard will respond to 
these requests, returning the deleted data. 
The use of xclipboard allows the value of a selection to survive the termination of the origi- 
nal selection owner. 
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12 

Geometry Management 

This chapter discusses how composite and constraint widgets manage the 
layout of widgets, and how to write your own simple composite and constraint 
widgets. 
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12 
Geometry Management 

Geometry managing widgets lay out your application's widgets on screen according to cer- 
tain rules. You cannot hardcode the position of widgets in an application because X applica- 
tions can be resized and they must reposition their widgets to take advantage of the available 
space. Because of the window manager, even the initial size of the application may not be 
the application's preferred size. 
Chapter 3, More Techniques for Using Widgets, demonstrated how you can use existing com- 
posite widgets such as Box and constraint widgets such as Form in the application. You can 
control widget layout rules with resources. However, you may find that no existing compos- 
ite or constraint widget can be configured with resources to have the layout rules you need. 
In this case, you will need to write your own composite or constraint widget or modify an 
existing one. However, before embarking on writing one of these widgets, you should realize 
that composite and constraint widgets are complex. First investigate the alternatives! Per- 
haps you can find a composite or constraint widget from another widget set that has the lay- 
out characteristics you need. If you determine that you have no alternative but to write your 
own composite or constraint widget, you should keep it as simple as possible. It is much eas- 
ier to write a special-purpose widget that handles a limited layout situation than it is to write 
a general-purpose composite or constraint widget like Box or Form. 
A composite widget is defined as any widget that is a subclass of the Xt-defined class Com- 
posite. A constraint widget is any widget that is a subclass of the Xt-defined class Con- 
straint. Constraint is a subclass of Composite. As you may recall, a composite widget is the 
simplest kind of geometry-managing widget; it handles all its children equally, or handles 
each child in a fixed way. For example, the Box widget handles all of its children equally. 
As an example of a special-purpose composite widget, Section 12.2 describes a composite 
widget called ScrollBox that manages two scrollbars and a main window. This widget 
requires that it have exactly three children added in a particular order. 
A constraint widget has all the characteristics of composite widgets but maintains configur- 
able data about each child so that it can cater to the needs of each child. By setting the con- 
straint resources of a child of a constraint widget, you configure the constraint widget's lay- 
out policy for that child. Constraint widgets are inherently more powerful than composite 
widgets, but are also more complicated to write. A constraint widget requires all the code of a 
composite widget, plus code to handle the constraints of each child. Because of this com- 
plexity, you should hesitate even further before attempting to write a constraint widget. As 
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If user specifies shell geometj, resize methods called from top down 

Figure 12-3. Initial geometry negotiation, if resizing is necessary 

the XtQueryGeometry ( ) call, and then do different things depending upon which of the 
three different answers it receives from the child. The XtGeometryAlmost answer 
includes a suggested compromise. The change_managed or resize method will decide 
on a new size based on the compromise, and may or may not make another XtQuery- 
Geometry() call to make this suggestion to the child. The code to perform all of this is 
extensive because the suggestions and answers are in the form of structures with several 
fields. Paned takes the height of a pane from the height returned by the child query, but only 
if the child returns XtGeometryAlmost. Since Viewport manages only one child (in addi- 
tion to the scrollbar widgets it creates), it queries that child for its geometry in its own 
query_geomet ry method (called when queried by its parent), and in its re s i z e method. 
Notice that this process can result in the resize, change_managed, and possibly the 
query_geometry methods of every widget being called, but the geometry_manager 
method does not play a part. 

Once this process is complete, XtRealizeWidget ( ) calls the realize methods of all 
the widgets and actually creates windows for them. Up to this point, all the methods were 
simply changing the widget size and position parameters in Xt structures, not the sizes of 
actual windows. XtRealizeWidget ( ) also maps all managed widgets. 

12.1.2 

User Resizes the Application 

When XtRealizeWidget ( ) returns, most applications call XtAppMainLoop (). Inter- 
nally, this calls the Xlib call X_NextEvent ( ) which sends the batch of queued window cre- 
ation and window map requests to the server/f Most window managers can intercept the 
mapping request for the top-level window and draw a rubber-band outline of the application 

You can find out more about the network optimization done by Xlib in Volume One or Volume Zero. 
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on the screen, ready for the user to place or resize the application. With certain settings mwm 
can either place windows for you or allow you to place and size them. If the user simply 
places the application, no new geometry negotiation takes place. But if the user resizes the 
application, a new round of geometry negotiation takes place, identical to the process 
described above where the user specified a top-level widget geometry. 

In other words, the process that occurs when the user resizes the application with the window 
manager is the same as when the user specifies top-level widget geometry with resources or 
the command line. This is also the same as when the user later resizes the existing applica- 
tion. This process was illustrated in Figure 12-2 and Figure 12-3. 

This process uses all the methods except geometry_manager. 

12.1.3 

Widget Desires a Size Change 

When an application sets a widget resource that affects what is displayed in the widget, it 
may be logical for the widget to ask its parent for a new size. This would occur in the 
set_values method of the widget. The widget sets its desired geometry into its Core 
geometry fields (width, height, x, y, and border_width). Xt finishes calling all the 
set_values methods (because they chain), and then calls XtMakeGeometry- 
Request ( ) to ask the parent widget for a geometry change. Note that the set_values 
and initialize methods are the only place where widgets are allowed to set their own 
size directly. (In set_values they can do so only because of an XtVaSetValues ( ) call 
to change a resource that affects geometry.) 

Figure 12-4 shows what happens when a widget requests a size change. 

Of course, composite widgets often want a size change because their children have asked to 
be resized. The composite widget has no knowledge of what caused the child's size change. 
Therefore, composite widgets call XtMakeGeometryRequest () themselves to see if 
their parent will allow them to change size. Composite widgets should request such a 
change; otherwise their parent may have unused space or have other children that need more 
space. However, handling the variety of responses to the request is not trivial. 

For both simple and composite widgets, Xt calls the geometry_manager method of the 
parent widget when XtMakeGeometryRequest ( ) is called, and the method is responsi- 
ble for deciding whether to except, reject, or compromise on the requested geometry. The 
geometry_manager method may have to ask its parent to decide whether it can accept its 
child's proposal. If so, it makes another XtMakeGeometryRequest ( ) call. This can go 
on to arbitrary depth, and the final answer will trickle back down to the parent of the original 
requestor. The XtMakeGeometryRequest ( ) call itself will change the child's geometry 
if the answer is yes. If the answer is no, the child gets this information and may try another 
geometry. If the answer is a compromise, then the child will get the compromise information 
returned in its call to XtMakeGeometryRequest ( ) and make another request to be able 
to proceed. More on this interaction in Section 12.2.6. 
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Although the widget code did nothing, the set_values method sets the new values speci- 
fied through resources into the Core fields. If the XtMakeGeometryRequest ( ) request 
is denied by the parent, Xt sets these Core fields back to their original values. If the parent 
suggests a compromise, the set._values_almost method, which is described below, is 
called. 

If the widget whose size is changed is a widget with children, the negotiation process is the 
same, except that when it is complete the children of the widget need to be laid out, and if the 
children have children they need to be laid out too, and so on. 

12.2 Writing a Composite Widget 

The process of writing a composite widget is the same as writing a simple widget. You copy 
the three files of some existing composite widget, perhaps Composite itself, make global 
name changes to make the files a skeleton for a distinct class, and then write new methods. 
As mentioned earlier, writing a general-purpose composite widget is not a trivial task and 
should be done only when other options fail. Because composite widgets have no user inter- 
face, you may be able to find a composite widget with the proper characteristics from another 
widget set. There are several public domain widget sets to look in. Note, however, that com- 
mercial widget set vendors may design in a private protocol between their composite widgets 
and their children, which make the composite widgets unable to correctly manage widgets 
from other sets. And if you are writing a commercial product, you may have to pay a binary 
license fee to the commercial widget set vendor for each copy of your product. Especially 
for large software houses, it is a good idea to have at least one programmer adept at writing 
composite widgets and the query_geometry methods of simple widgets. 
Small scale composite widgets that handle a small set of circumstances are not difficult to 
write, because you can make a number of simplifying assumptions. As an example, this sec- 
tion describes a very simple composite widget called ScrollBox, which is designed to manage 
a BitmapEdit widget (or any other main widget) and two Scrollbar widgets. It handles only 
these three widgets, and they must be added in a particular order. Because we know that the 
geometry preferences of these three widgets (the bigger the better, but no size in particular), 
we can dispense with querying them about their preferred geometry. We also know that none 
of our children will request to be resized. Therefore, we do not need a geometry_man- 
ager method. 
A ScrollBox widget is shown managing BitmapEdit and two scrollbars in Figure 12-5. 

Geometry Management 347 



I i 

Figure 12-5. A ScrollBox widget at two different sizes 
The Athena Viewport widget does scrollbar management in a more general way than does 
ScrollBox. It is a subclass of Form that takes any main window as a child and creates 
scrollbars. It shows only a small portion of the main window and uses the scrollbars to deter- 
mine which portion of the main window is shown. But Viewport is several times larger and 
more complicated than ScrollBox, because it includes the scrollbar callback functions and 
because it honors a child's geometry preferences. ScrollBox is a modest widget that manages 
the geometry of scrollbars, leaving their connection with the main window up to the applica- 
tion. This demonstrates the essential elements of a composite widget without too much com- 
plication. 
The ScrollBox widget code, along with a version of xbitmap that uses it, is available in the 
example source in the ch09 directory. It lays out its children by adjusting the width and 
height of the three children so that they fill the ScrollBox widget, while keeping the width of 

1-It is worth noting that the Box widget fails miserably in managing scrollbars, while Form is adequate but has the an- 
noying characteristic that it resizes the width of the scrollbars as well as their length, sometimes resulting in bloated 
or minuscule scrollbars. 
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Example 12-3. ScrollBox: the query_geometry method (continued) 
reply_return->request_;node I = CWWidth; 
} 
else 
result = XtGecmetryYes; 
} 
return (result) ; 
} 
Although the query_geometry method has the same role in all widgets, composite and 
simple, a composite widget's size preference depends on its children. Normally this means 
the query_geometry method will query its children and try different layouts until it 
arrives at the geometry, or some approximation of it, suggested by its parent. This calcula- 
tion is complicated because the widget may have any kind of child, and their responses to 
geometry suggestions are unpredictable. ScrollBox ignores this complexity because it knows 
exactly what kinds of children it will have and what their characteristics are. Therefore, its 
query_geometry method is basically the same as the query_geometry method of a 
simple widget. 
To be more precise, what this query_geometry method does is accept any size suggested 
by the parent which is larger than the minimum useful size of the application. When the sug- 
gested size is too small, the query_geometry method uses the minimum useful size as a 
compromise. Note, however, that this is really hardcoding the characteristics of the child into 
our composite widget. It would be better to add resources to control the minimum useful 
size. 

12.2.2 

Laying Out Child Widgets 

Composite widgets need to calculate a layout and manipulate their child widgets from 
set_values, from resize, and from change_managed. Therefore, in most composite 
widgets this common code is placed in a single routine called DoLayout. Example 12-4 
shows the DoLayout routine from ScrollBox. 

Example 12-4. ScrollBox: private routine to lay out child widgets 
/* ARGSUSED * / 
static DoLayout (w) 
Widget w; 
{ 
ScrollBoxWidget sh = (ScrollBoxWidget) w; 
Widget main, vscroll, hscroll; 
Widget child; 
Dimension row, mh; /* main window */ 
Dimension vh; /* vertical scrollbar length (height) */ 
Dimension hw; /* horizontal scrollbar length (width) */ 
Position vx; 
Position hy; 
int i; 

if (shq->composite.nunl_children != 3) 
XtAppError (XtWidgetToApplicationContext (sh), 
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Example 12-4. ScrollBox: private routine to lay out child widgets (continued) 
"ScrollBox: must manage exactly three widgets. "); 
for (i = 0; i < sh->composite.num_children; i++) { 
child = sh->composite.children[ i ] ; 
if (!XtIsManaged(child) ) { 
XtAppError (XtWidgetToApplicationContext (shq), 
"ScrollBox: all three widgets must be managed. "); 
} 
/* Child one is the main window, two is the vertical scrollbar, 
* and three is the horizontal scrollbar. */ 
main = shq->composite.children[ 0 ] ; 
vscroll = sh->composite.children[l ] ; 
hscroll = sh->composite.children[2 ] ; 
/* Size all three widgets so that space is fully utilized. */ 
mw = sh->core.width- (2 * sh->scrollBox.h_space) - 
vscroll->core.width - (2 * vscroll->core.border_width) 
- (2 * main->core.border_width) ; 
mh = sh->core.height - (2 * sh->scrollBox.v_space) - 
hscrol l->core, height - (2 * hscrol I->core. border_width) 
- (2 * main->core.border_width) ; 
vx = main->core.x + mw + sh->scrollBox.h_space + 
main->core.border_width + vscroll->core.border_width; 
hy = main->core.y + mh + shq->scrollBox.v_space + 
main- >core. border_width + hscrol I- >core. border_width; 
vh = mh; /* scrollbars are always same length as main window */ 
hw : row; 
XtResizeWidget(main, row, mh); 
XtResizeWidget(vscroll, vscroll->core.width, vh); 
XtMoveWidget(vscroll, vx, vscroll->core.y); 
XtResizeWidget(hscroll, hw, hscroll->core.height); 
XtMoveWidget(hscroll, hscroll->core.x, hy); 
} 
In general, DoLayout moves and resizes the child widgets according to its layout policy. 
This routine may query the children with XtQueryGeometry ( ) before making decisions, 
but it is not required to. In this case, there is no need to because ScrollBox handles only two 
types of widgets with no size preferences. 
DoLayout is passed only one argument, ScrollBox's own widget ID (a pointer to its widget 
instance structure). But the composite children field in ScrollBox's instance structure is 
an array of the IDs of all the children, and hum_children is the number of children.% 
When each child is added to a composite widget, its ID is added to the children field of 
the composite part of the instance structure, and the hum_children field is incremented. 
Therefore, the code to lay out the children is usually a loop that treats each child one at a 

% Incidentally, the children and num_children fields are resources. However, they are read-only from outside 
the widget code; the application should never set them with XtSetValues ( ). 
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time. This often takes two passes, since the routine needs to know which children are 
managed before it can determine their final geometries. All children, even unmanaged ones, 
are listed in the chi l dren and num_children fields. 
This particular DoLayout procedure makes sure that there are exactly three children and 
that they are all managed. Then, it calculates the positions and sizes for all the children so 
that they will fill all the available space in ScrollBox's own window. Finally, it calls Xt- 
ResizeWidget ( ) and XtMoveWidget (), which check to see if there was any change 
before making Xlib calls to move and resize the windows. 

12.2.3 

The change_managed Method 

In every composite widget, the change_managed method is called once (and only once, 
even when there are multiple children) during the XtRealizeWidget ( ) process to deter- 
mine an application's initial layout, change, managed is also called when an application 
later unmanages a managed widget or manages an unmanaged widget (as long as the 
XtNmappedWhenManaged resource has its default value). Therefore, change_- 
managed also calls DoLayout. 

An application unmanages a widget to remove the widget from visibility without destroying 
it. and at the same time to tell the composite widget to change the layout of the remaining 
widgets to fill the gap. This is done by calling XtUnmanageCh-i 1 d ( ) or XtUn_anage- 
Ch-i l dren (). The application can then make the composite widget redisplay the widget by 
calling XtManageChild() or XtManageChildren(). This response depends on the 
Core XtNmappedWhenManaged resource having its default value, True. When set to 
False, the management state has no effect on mapping, and the application must call Xt- 
MapWidget ( ) and XtUnmapWidget ( ) instead. Usually an application does this so that 
a widget will become invisible without triggering a re-layout to fill in the space it has 
vacated. Therefore, change_managed need not check the XtNmappedWhenManaged 
resource of each child. Example 12-5 shows the change, managed method of ScrollBox. 

Example 12-5. A basic change_managed method 
static void ChangeManaged(w) 
ScrollBoxWidget w; 
{ 
ScrollBoxWidget sbw = (ScrollBoxWidget) w; 
DoLayout (sbw) ; 
} 

12.2.4 

The geometry_manager Method 

The geometry_manager method responds to requests by the children to be resized. 
ScrollBox does not manage widgets that request to be resized, so theoretically it should not 
need a geometry, manager, but as of R4, Xt requires that all composite widgets have one. 
ScrollBox's geometry manager method is very simple, and is shown in Example 12-6. 
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Example 12-6. A simple geometry_manager method 
static XtGeometryResult 
GeometryManager (w, request, reply) 
Widget w; 
XtWidgetGeometry *request; 
XtWidgetGeometry *reply; 
{ 
return XtGeometryYes; 

Section 12.2.6 describes what would take place in a more complex geometry_manager, 
and Section 12.4.6 provides an example. 

You have now seen all the code in ScrollBox! To summarize, a very basic composite widget 
such as ScrollBox has a standard initialize method, resize and change_managed 
methods that just call DoLayout, and a set_values method that calls DoLayout when 
any resource that affects layout is changed. The DoLayout routine actually lays out the 
children. The widget's query_geometry method is basically just like a simple widget's 
query_geometry. Now we'll move on to describe what may be added to this skeleton to 
make more fully-featured composite widgets. 

12.2.5 

XtQueryGeometry and the query_geometry Method 

We have mentioned that XtQueryGeometry() calls a child's query_geometry 
method, but not the details of how this works. The query_geometry method for simple 
widgets is described in Chapter 7, Basic Widget Methods. The role of this method in compo- 
site widgets is the same, but the details of its job are different. You may recall that this 
method is passed pointers to two XtWidgetGeometry structures, one which specifies the 
parent's proposed geometry, and the other which is used by the child to return a compromise 
geometry. These two structures are allocated by the method that calls XtQuery- 
Geometry() and passed as pointers to that call. The XtGeometryResult enum 
returned by the query_geometry method is passed right through as the returned value of 
XtQueryGeomet ry (). 

Composite and constraint widgets play the role of both parent and child. When you write a 
composite widget, you may call XtQueryGeometry ( ) in several places to get the child's 
response to your proposed size. You will also need to write a query_geometry method so 
that your composite can respond to its parent's XtQueryGeometry ( ) request. 

A query_geometry method in a composite widget should base its response on the size 
preferences of its children. It should calculate a new layout based on the proposed geometry 
passed in, and then query its children to get their opinions of their new geometry. If any of 
the children is a composite widget, they may query their children, and so on. Therefore, 
these requests tend to trickle down to the lowest widget in the hierarchy. ScrollBox took the 
biggest shortcuts in its query_geometry method. Not only didn't it query its children, but 
it hardcoded its response based on the characteristics of the kind of main window it expected. 
This would be the first place to begin improving ScrollBox. 
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Note, however, that a composite widget is allowed to be authoritarian and not ask its children 
whether they like the sizes they are about to be given. However, this kind of composite 
widget will not be suitable as a parent of a widget that really needs certain size preferences. 

A parent must specify a complete proposed geometry when calling XtQueryGeometry (), 
not just the changes it intends to make. 

12.2.6 

XtMakeGeometryRequest and the geometry_manager Method 

XtMakeGeometryRequest ( ) calls are made for two reasons. First, when a composite 
widget honors its children's size preferences, it may find that its current size is inadequate to 
lay out its children. In this case, it should ask its parent to be resized by calling XtMake- 
GeometryRequest (). Second, Xt calls XtMakeGeometryRequest ( ) for a widget 
when the application has changed a resource that affects geometry. 
As mentioned above, XtMakeGeometryRequest() calls the parent's geometry_ 
manager method. The parent's geometry, manager has the job of deciding whether the 
size proposed by the child is acceptable. A subclass of Composite must either define a 
geometry._manager method, or set this field in the class structure to NULL, because there 
is no default method to inherit. The XtInheritGeometryManager symbol can be used 
only in subclasses of a class that defines a geometry, manager method. Any composite 
widget allowing its children to suggest resizing will require a geometry_manager meth- 
od of its own. 
The way the arguments and returned values are passed between XtMakeGeometry- 
Request () and the parent's geometry_manager method is almost exactly parallel to 
the way XtQueryGeometry () calls the child's query_geometry method. Both calls 
take pointers to two structures of the same types where one is used for a returned compro- 
mise. Both take no more arguments other than the widget ID. Both return an enum value of 
type XtGeometryResult. The returned value of the geometry, manager method is, 
generally speaking, passed through as the returned value of XtMakeGeometry- 
Request ( ). Review Section 7.6 so that these structures, their fields and values, and the re- 
turned values are fresh in your mind. 
One difference is that the geometry_manager method can return a fourth enum value, 
XtGeometryDone (in addition to XtGeometryYes, XtGeometryNo, and Xt- 
GeometryAlmost). The return codes of the geometry, manager method are summa- 
rized in Table 12-1. 
XtGeometryDone means that geometry, manager approves of the change and has ac- 
tually made the change. XtMakeGeometryRequest() never returns XtGeometry- 
Done though; it returns XtGeometryYes when the geometry_manager returns 
XtGeometryYes or XtGeometryDone. When the geometry, manager returns Xt- 
GeometryYes, the XtMakeGeometryRequest ( ) call itself makes the size change. All 
these shenanigans simply allow the parent to make the size change by calling its normal lay- 
out code or to let XtMakeGeometryRequest ( ) do it, depending on which is most conve- 
nient. 
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Table 12-1. Return codes of geometry_manager Method 

Code 

XtGeometryNo 
XtGeometryAlmost 
XtGeometryYes 

XtGeometryDone 

Description 

Requested change is denied. 
A compromise is suggested. 
Requested change is accepted, let Xt:MakeGeomet: 
Request: ( ) make change. 
Requested change is accepted, I have made change. 

XtGeometryDone means that geometry_manager approves of the change and has ac- 
tually made the change. XtMakeGeometryRequest () never returns XtGeometry- 
Done though; it returns XtGeometryYes when the geometry_manager returns 
XtGeometryYes or XtGeometryDone. When the geometry_manager returns Xt- 
GeometryYes, the XtMakeGeometryRequest ( ) call itself makes the size change. All 
these shenanigans simply allow the parent to make the size change by calling its normal lay- 
out code or to let XtMakeGeometryRequest ( ) do it, depending on which is most conve- 
nient. 
The second difl'erence between the way the query_geometry and geometry_manager 
methods are invoked is that XtMakeGeometryRequest ( ) and the geometry_manag- 
er method interpret the XtGeometryNo returned value differently. For XtMake- 
GeometryRequest () and geometry_manager, it has its intuitive meaning that the 
requested change is denied. For query_geometry and XtQueryGeometry (), the sym- 
bol should really be XtGeometryNoChange. Since this symbol doesn't exist, Xt- 
GeometryNo has to do double duty, meaning in this case that the proposed size and current 
size are the same. 
The final difference is an additional mask for the request_mode field of the XtWidget- 
Geometry structure that contains the proposed change. In XtMakeGeometry- 
Request ( ) requests, the mask xtCwQueryOnly can be ORed with the masks that identi- 
fy which fields in the proposed geometry the child considers important. This indicates that 
the proposed change should not be made, but that the geometry_manager method should 
fill in the return structure with the changes it would have made. This flag is used whenever a 
widget is making an XtMakeGeometryRequest () from its geometry_manager 
method: these requests are intermediate (triggered by requests from children). The compos- 
ite widget does not actually want to be resized until it has made a suggestion for its own size 
to its parent, received an answer from the parent, recalculated the layout of its children, and 
queried its children, if necessary, to see that the new size is adequate for everybody. 
This also makes it obvious that the geometry_manager method you write for your com- 
posite widget must be prepared to handle the xtCwQueryOnly mask. It should calculate a 
layout but not actually move or resize any widgets. 
ScrollBox does not need a geometry_manager method because it knows that its children 
will never make geometry requests. However, any composite widget that accepts all kinds of 
children requires a geometry_manager method. In Section 12.4.6 below, the 
geometry_manager method of the Form widget is shown and described. 
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Composite class by specifying the symbolic constant XtlnheritlnsertChild in the 
class structure initialization. A class would replace the default insert_child method to 
control the position of each child added, or to limit the number or classes of widgets that can 
be added. 
A composite widget can control the position of each child added by calling a function whose 
pointer is stored in the instance part field insert_position. The function should return 
the number of widgets before the widget. The XtNinsertPosition resource sets this 
function pointer. The default insert_position function returns the current number of 
children. Of course, because this resource's value is a function pointer, it can be specified in 
the application only at run time, never through the resource files or command line. 
The delete_child method removes the ID of a child from the child array and is called 
when the application calls XtDestroyWidget (). This method is almost always inherited 
from Composite by specifying the symbolic constant XtlnheritDeleteChild in the 
class structure initialization. 

12.3 How Constraint Management Works 

The first thing to realize about constraint widgets is that everything said about composite 
widgets is still true. Because Constraint is a subclass of Composite, all the methods de- 
scribed above are still present and have the same tasks. However, constraint widgets also 
maintain a structure lull of data attached to each child, set through resources. Every time it 
lays out the children, the constraint widget reads this data to determine how to handle that 
child. Of course, it still may query each children to get its opinion of a new size. The con- 
straint information adds another level of complexity to the situation. 

Like composite widgets, constraint widgets can be drastically simplified by reducing flexibil- 
ity and features. The Athena Form widget, for example, never queries its children for their 
geometry input and never asks its parent for a size change. Furthermore, its constraints for 
each child are quite limited. This makes Form quite short and simple, but also means that it 
doesn't always do the right thing. 

12.4 Writing a Constraint Widget 

The following sections describe the portions of the Athena Form widget that relate to 
geometry management. We have chosen the Athena Form widget instead of the Motif Form 
widget because the Athena Form widget is less than one quarter the size and is much simpler 
to understand. The principles at work are similar, and an understanding of the Athena imple- 
mentation should give you a good start towards understanding geometry management under 
Motif. 

However, before we start, a review of the constraints of the Athena Form widget is in order. 
As you should remember, constraints appear to the user to be resources of the child widgets 
managed by the Form. Looking at these resources gives you a good idea of the kinds of 
things that can be done with Athena Form constraints. 
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The resources XtNhorizDistance and XtNfromHoriz specify the widget position 
in terms of a specified number of pixels horizontally away from another widget in the 
form. As an example, XtNhorizDistance could equal 10 and XtNfromHoriz 
could be the widget ID of another widget in the Form. (When specified in a resource file, 
XtNfromHoriz is set using the instance name of another widget in the form.) The new 
widget will always be placed 10 pixels to the right of the widget defined in XtNfrom- 
Horiz, regardless of the size of the Form. If XtNfromHoriz equals NULL, then Xt- 
NhorizDistance is measured from the left edge of the Form. 

Similarly, the resources XtNvertDistance and XtNfromVert specify the widget 
position in terms of a specified number of pixels vertically away from another widget in 
the Form. If XtNfromVert equals NULL, then XtNvertDistance is measured from 
the top of the Form. 

When set in the application, the values for XtNfromHoriz and XtNFromVert must 
be widget IDs. But in the resource database, widget names are used instead, since the ac- 
tual widget ID changes each time the application is run. Athena uses an Xmu converter 
from widget name to widget ID, which is useful when setting constraints from resource 
files. However, Motif does not provide such a converter. 

The XtNtop, XtNbottom, XtNleft, and XtNright resources tell the Form where to 
position the child when the Form is resized. The values of these resources are specified 
by the enum XtEdgeType, which is defined in <XI l/Xaw/Form.h>. 

The values XtChainTop, XtChainBottom, XtChainLeft, and XtChainRight 
specify that a constant distance is to be maintained from an edge of the child to, respec- 
tively, the top. bottom, left, and right edges of the Form. 

The value XtRubber specifies that a proportional distance from the edge of the child to 
the left or top edge of the Form is to be maintained when the Form is resized. The pro- 
portion is determined from the initial position of the child and the initial size of the Form. 
Form provides a StringToEdgeType conversion to allow the resize constraints to be 
easily specified in a resource file. 

12.4.1 

The Core Resource List 

The Form widget has only one resource of its own, XtNdefaultDistance, as shown in 
Example 12-7. This resource is used only as the default for two of the Constraint resources, 
XtNhorizDistance and XtNvertDistance. XtNdefaultDistance is used to set 
the instance field default_spacing, which is used in only one place in the widget, in the 
Constraint init ial i ze method described in Section 12.4.4. 

Example 12-7. Form: the Core resource list 
#define Offset (field) XtOffsetOf (FormRec, form. field) 
static XtResource resources[ ] = { 
{ 
XtNdefaultDistance, 
XtCThickness, 
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Example 12-7. Form: the Core resource list (continued) 
XtRInt, 
sizeof ( int), 
Offset (default_spacing), 
XtRIrmediate, 
(XtPointer) 4 
} 
}; 
#undef Offset 

12.4.2 

The Constraint Resource List 

The Form widget has three groups of constraint resoues. XtNhorizDistance, Xt- 
NfromHoriz, XtNvertDistance, and XtNfromVert together control the initial posi- 
tion of a child. XtNtop, XtNleft, XtNbottom, and XtNright govern repositioning of 
the child when Form is resized. The XtNresizable resource controls whether the 
geometry_manager of this widget will honor requests to change the geometry of this 
child. Note that XtNresizabqe does not control whether this constraint widget can resize 
a child--only whether or not it will do so because of a request from the child.-l 

For more details about how these constraint resources work, read about them on the reference 
page for the Form widget in Volume Five, X Toolkit lntrinsics Reference Manual. 

Constraint resources are also called simply constraints, particularly because they are stored 
in a Core instance field called constraints. Example 12-8 shows Form's constraint re- 
source list. 

Example 12-8. Form: constraint resource list 
static XtEdgeType defEdge = XtRubber; 

#define Offset (field) XtOffsetOf (FormConstraintsRec, form. field) 
static XtResource formConstraintResources [ ] = { 
{ 
XtNhorizDistance, 
XtCThickness, 
XtRInt, 
sizeof (int), 
Offset (dx), 
Xt RIrmedi at e, 
(XtPointer) DEFAULTVALUE 
), 
{XtNfromHoriz, XtCWidget, XtRWidget, sizeof (Widget), 
Offset (horiz_base), XtRWidget, (XtPointer)NUI/}, 
{XtNvertDistance, XtCThickness, XtRInt, sizeof(int), 
Offset (dy), XtRInnediate, (XtPointer) DEFAULTVALUE}, 
{XtNfromVert, XtCWidget, XtRWidget, sizeof(Widget), 
Offset (vert_base), XtRWidget, (XtPointer)NULL}, 

{XtNtop, XtCEdge, XtREdgeType, sizeof(XtEdgeType), 

%The fact that Form does not provide individual control over the resizability of each child is a major weakness 
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Example 12-10. Form: class structure initialization (continued) 

{ I* 
I* 
I* 
I* 
i. 
I* 
}, 
{ I* 
I* 
I* 
I* 
I* 
i* 
I* 
I* 
}, 
{ I* 
I* 
} 
} 

Ccposite class fields */ 
gemetry_anager * / GeometryManager, 
change_anaged * / ChangeManaged, 
insert_child */ Xt Inherit InsertChild, 
delete_child */ Xt InheritDeleteChi id, 
extension */ NULL 

Constraint class fields */ 
subresources * / formConst raintResources, 
subresource_count * / XtNumber ( formConstraintResources), 
constraint_size */ sizeof (FormConstraintsRec), 
initialize */ Constraint Initialize, 
destroy * / NULL, 
set_values * / ConstraintSetValues, 
extension */ NULL 

Form class fields */ 
layout */ Layout 

WidgetClass formWidgetClass = (WidgetClass)&formClassRec; 

Note that the Form class is the first widget we have shown that defines a class part field--a 
method of its own, called layout. Since this method is not known to Xt, Xt will never call 
it. The widget must invoke this method itself at the appropriate times (you will see this invo- 
cation in the methods below). This code is made into a method instead of just a private func- 
tion only to make it possible for subclasses of this widget to inherit or replace the method. 
Having such a method requires that the widget have a class_part_init method to 
handle the inheritance if a subclass specifies the layout method with the symbolic constant 
XtlnheritLayout (also defined in this class's private header file). 
Section 12.2.1 described which Core and Composite methods are required for composite 
widgets, and how to initialize the other Core and Composite fields for a composite widget. 
The same is true for constraint widgets. 

However, the Constraint part is probably new to you. The ConstraintClassPart struc- 
ture contains seven fields. The first three fields are where the constraint resource list, the 
number of resources, and the size of the constraint instance structure are entered. This re- 
source list and instance structure were described in the last section. These fields are analo- 
gous to the resources, num_resources, and widget_size fields in the Core class 
part. 
The three next fields, initial ize, destroy, and set_values are methods defined by 
the Constraint class. These methods have the same field names as methods of Core, but are 
fields of a different structure, and contain pointers to different functions that you may need to 
write. To differentiate Constraint methods from the Core methods, we will precede the 
names of Constraint fields with the word "Constraint" and the names of Core fields with the 
word "Core" throughout this chapter. 
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Two of the three Constraint methods will be described where they fit in below. We'll de- 
scribe one of them, Constraint destroy', now, because it is not used in Form and is less like- 
ly to be needed in the constraint widgets you may write. The Constraint destroy method is 
called when a child is destroyed, just before the Core destroy method of the child. It is re- 
sponsible for freeing any memory allocated by the constraint widget that was used to manage 
that child. However, like the Core destroy method, it does not need to free memory allo- 
cated by Xt, such as the constraint data structure for the child. 

12.4.4 

The Constraint initialize Method 

The Constraint initialize method is called when a widget is created, soon after the Core 
initialize method. It has the same two responsibilities as the Core initialize method, 
and one additional responsibility. It must: 

Validate the ranges of resource settings, since they may be user-supplied. 

Compute the value of any private constraint instance part fields that depend on constraint 
resource values (public constraint instance part fields). 

Set child Core geometry fields to match the constraint resources. For example, if a con- 
straint for the maximum height of a widget is set and the initial value set by the child is 
larger, the Constraint initialize method resets the height field in the Core instance 
structure. 

However, like the Core initialize method, the Constraint initialize method is re- 
sponsible only for constraint resources and for Core geometry resources. It need not handle 
any resources of superclasses (other than the Core geometry resources). 
The Form widget performs only one of the tasks listed above, initializing constraint re- 
sources. In Form's case, the Constraint initialize method (shown in Example 12-1 l) 
simply sets the initial values of the XtNvertDistance and XtNhorizDistance con- 
straint resources to the current value of the XtNdefaultDistance Form resource, unless 
the user has specified a value for either constraint resource. This is done only so that the ap- 
plication can set the Form resource once and have it apply to every child that does not over- 
ride the value. 
Form doesn't validate the values of any user-supplied resource values as it should. For ex- 
ample, the user may supply a negative value for the XtNhorizDistance or XtNvert- 
Distance resources. This would certainly make the layout look bad, but it could also 
cause the Form widget to go into an infinite loop on geometry negotiations. In general, all 
initialize methods in Core and Constraint should check for ranges of reasonable values 
of resources where this makes sense. Range checking eliminates a potential source of bugs. 
Range checking in set_values is also a good idea to give the programmer good warning 
messages). 
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Example 12-11. Form: the Constraint initialize method 
#define DEFAULTVALUE -9999 
/* ARGSUSED */ 
static void ConstraintInitialize (request, new) 
Widget request, new; 
{ 
FormConstraints form = (FormConstraints) new->core, constraints; 
FormWidget fw = (FormWidget)new->core.parent; 
form->form.virtual_width = (int) new->core.width; 
form->form.virtual_height = (int) new->core.height; 

if (form->form.dx == DEFAULTVAI/JE) 
form->form.dx = fw->form.default_spacing; 
if (form->form.dy == DEFAULTVALUE) 
form->form.dy = fw->form.default_spacing; 

Note that the Constraint instance part structure (FormConstraints) and the Form widget 
instance structure (FormWidget) are accessed by casting two different fields of the child's 
instance structure passed in. 
The Constraint initialize method and the child's Core initialize are passed the 
same two copies of the child's instance structure: request, and new. The request 
widget is the widget as originally requested. The new widget starts with the values in the re- 
quest, but it has already been updated by calling all superclass init ia 1 i z e methods. 

12.4.5 

The class_part_init Method 

The class_part_init method should be present in a class that defines new methods in 
its class part structure. These new methods will never be called by Xt since Xt has no knowl- 
edge of when to call them. They can only be invoked directly from the widget code. The 
purpose of making them methods instead of just functions is to allow subclasses to inherit or 
replace the functions. The class_part_init method actually resolves this inheritance 
by setting each method field to the pointer provided by this class (the subclass is inheriting 
the method) or to the pointer provided by the subclass (the subclass is replacing the method). 
Example 12-12 shows a class_part_init method for a class that defines only one new 
method in its class part structure. This method is the Form widget's layout code. 

Examp 12-12. Form: the class_part_method 
static void ClassPartInitialize(class) 
WidgetClass class; 
{ 
register FormWidgetClass c = (FormWidgetClass) class; 

if (c->forn_class.layout == XtInheritLayout) 
c->forn_class.layout = Layout; 
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Example 12-14. Form private functions: RefigureLocations and the layout method (continued) 
if (result == XtGecmetryAlmost) 
result = XtMakeResizeRequest ( fw, (Dirension)maxx, 
(Dimension)maxy, NULL, NULL ); 
fw->form, old_width = fw->core.width; 
fw->form, old_height = fw->core.height; 
ret_val = (result == XtGecmetryYes); 
} else ret_val = False; 
return ret_val; 
} 
The layout method treats one child at a time, first initializing the layout_state private 
constraint instance field of each child to LayoutPending. The LayoutChild routine 
will start from this value. Next, it calls LayoutChild for each child, and at the same time 
keeps a running total of the sizes of the children so that when the loop is finished it knows 
how big to be to fit all the children. Finally, it requests of its parent that it be just big enough 
to fit its children. If the parent denies the request, the code makes no attempt to make another 
request. If the parent offers a compromise, it is accepted. The Form widget, in either case, 
may be too big or too small to fit its children. If it is too small, some of its children will be 
clipped. 
The LayoutChild routine is shown in Example 12-15. What it does is simple, although it 
is a little hard to follow because it is called recursively. It moves the child according to the 
XtNfromHoriz and XtNfromVert constraint resources/f These resources specify that a 
child be placed to the right of or below another particular child. 

Example 12-15. Form: the LayoutChild pdvate function 
static void LayoutChild (w) 
Widget w; 
{ 
FormConstraints form = (FormConstraints) w->core, constraints; 
Position x, y; 
Widget ref; 
switch (form->form. layout_state) { 
case Layout Pending: 
form->form, layout_state = LayoutInProgress; 
break; 
case LayoutDone: 
return; 
case LayoutInProgress: 
String subs [ 2 ] ; 
Cardinal nu_subs = 2; 
subs [ 0 ] = w->core.name; 
subs [ 1 ] = w->core.parent->core.name; 
XtAppWarningMsg (XtWidgetToApplicationContext (w), 
"constraintLoop", "xawFormLayout", 
"XawToolkitError", "constraint loop\ 
detected while laying out child\ 

Form resizes children only when it is resized--never during normal layout. 
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width and height of the Form widget are initialized in the Core initialize method and 
updated at the end of the resize method. 

Example 12-16. Form: the resize method 
static void Resize (w) 
Widget w; 
{ 
FormWidget fw = (FormWidget)w; 
WidgetList children = fw->composite.children; 
int numchildren = fw->composite.numchildren; 
Widget *childP; 
Position x, y; 
Dimension width, height; 

for (childP = children; childP - children < num_children; 
childP++) { 
FornConstraints form = (FornConstraints) 
(*childP) ->core. constraints; 
if (.'XtIsManaged(*childP) ) continue; 
x = TransfornCoord( (*childP)->core.x, fw->form.old_width, 
fw->core.width, form->form, left ) ; 
y = TransfornCoord( (*childP)->core.y, fw->form.old_height, 
fw->core.height, form->form.top ) ; 

form->form, virtual_width = 
TransformCoord((Position) ((*childP)->core.x 
+ form->form.virtual_width 
+ 2 * (*childP)->core.border_width), 
fw->form, old_width, fw->core.width, 
form->form, right ) 
- (x + 2 * (*childP)->core.border_width) ; 

form->form.virtual_height = 
Trans fornCoord ((Position) ( (*childP) ->core .y 
+ form- > form. virtual_height 
+ 2 * (*childP)->core.border_width), 
fw->form, old_height, fw->core.height, 
form->form, bottom ) 
- ( y + 2 * (*childP)->core.border_width); 

width = (Dimension) 
(form->form.virtual_width < i) ? 1 : 
form->form.virtual_width; 
height = (Dimension) 
(form->form.virtual_height < i) ? 1 : 
form->form.virtual_height; 

XtConfigureWidget( *childP, x, y, (Dimension)width, 
(Dimension)height, (*childP)->core.border_width); 

fw->form.old_width = fw->core.width; 
fw->form.old_height = fw->core.height; 

static Position TransfornCoord(loc, old, new, type) 
register Position loc; 
Dimension old, new; 
XtEdgeType type; 
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Form defines both the Core and Constraint set_values methods as empty functions that 
return False. An easier way to do this is to specify NULL for them in the class structure ini- 
tialization. 

12.4.9 

The change_managed Method 

The change_managed method is responsible for making the initial layout of an applica- 
tion and changing the layout when any child changes management state. Form's 
change, managed method (shown in Example 12-17) calls RefigureLocations to ac- 
tually do a layout. (RefigureLocations is a private routine equivalent to DoLayout in 
ScrollBox, described in Section 12.4.6.) Form's change, managed method also stores the 
previous size of the children in the virtual, width and virtual_height constraint 
part fields for use in the resize method as described in Section 12.4.7. 

Example 12-17. Form: the change_managed method 
static void ChangeManaged (w) 
Widget w; 
{ 
FormWidget fw = (FormWidget)w; 
FormConstraints form; 
WidgetList children, childP; 
int num_children = fw->composite.num_children; 
Widget child; 
/* 
* Reset virtual width and height for all children. 
*/ 
for (children = childP = fw->composite.children; 
childP - children < num_children; childP++) { 
child = *childP; 
if (XtIsManaged(child)) { 
form = (FormConstraints) child->core, constraints; 
if ( child->core.width != i) 
form->form.virtual_width = (int) child->core.width; 
if ( child->core.height != i) 
form->form.virtual_height = (int) child->core.height; 
RefigureLocations ((FormWidget)w) ; 

12.4.10 

The query_geometry Method 

Form's query_geometry method (shown in Example 12-18) is the minimal version, al- 
most identical to the one described for simple widgets in Chapter 7, Basic Widget Methods. 
The preferred_width and preferred_height instance variables are set in the Form 
class Layout method to the size that just fits the current layout. 
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Examp 12-18. Form: me query_geometrymeod 
static XtGeonetryResult PreferredGecrnetry( widget, request, reply 
Widget widget; 
XtWidgetGeonetry *request, *reply; 
{ 
FormWidget w = (FormWidget)widget; 

reply->width = w->form.preferred_width; 
reply->height = w->form.preferred_height; 
reply->request_mode = CWWidth I CWHeight; 
if ( request->request_mode & (CWWidth I CWHeight) == 
reply->request_mode & CWWidth I CWHeight 
&& request->width == reply->width 
&& request->height == reply->height) 
return XtGeonetryYes; 
else if (reply->width == w->core.width && reply->height == 
w->core.height) 
return XtGeonetryNo; 
else 
return XtGeometryAlmost; 

12.4.11 

Delaying Geometry Recalculation 

During an application's initial layout, the change_managed method of a composite widget 
is called only once even though many children may have been managed. However, after that, 
change, managed is called once for every child that changes management state. Many 
composite or constraint widgets, especially ones that have complicated layout code, provide 
a public function (such as the one shown in Example 12-19) that the application can call to 
turn off layout recalculation until a group of windows is managed or unmanaged, and then 
call again to trigger recalculation once the whole group of children has been managed or un- 
managed. 

To implement this delay, you need an instance variable to hold a Boolean value indicating 
whether to delay or not (no_refigure, in this case). You set and unset this variable in this 
public routine and you test it in change, managed. 

Examp 12-19. Form: epublicfunction rdelaying callschange_managed 
void XawFormDoLayout(w, doit) 
Widget w; 
Boolean doit; /* False, don't recalculate; True, do */ 
{ 
register FormWidget fw = (FormWidget)w; 

fw->form.no_refigure = !doit; 

if (XtIsRealized(w) && fw->form.needs_relayout ) 
RefigureLocations( fw ); 
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12.5 Compound Widgets 

A compound widget is a combination of widgets put together to make a higher-level, user-in- 
terface object. For example, a Viewport widget is itself a composite widget, but it automati- 
cally creates its own Scrollbar children. 
Compound widgets create their children in their .nA:.al .ze method, and set resources to 
position them. Often they also provide resources of functions that make it easy for the appli- 
cation to configure some characteristics of their children. The application can manipulate the 
children only through these resources, because it cannot access the widget IDs of the com- 
pound widget's subwidgets without breaking the rules of data hiding. Thus, compound widg- 
ets are convenient for programming, but they make it more difficult to take advantage of all 
the configurable aspects of the subwidgets. 
The main widget of the compound widget may be a subclass of Core, Composite, or Con- 
straint. If it is a subclass of Core, the widget manages the positions and sizes of its children 
manually whenever it is resized. The success of this strategy is dependent on the children 
never trying to resize themselves and on the application never trying to resize the children di- 
rectly.t The latter will not be a problem unless the application breaks the data-hiding rules 
by manipulating the child directly. The Text widget is an example of this kind of widget. It 
creates and manages its own scrollbar. 
Compound widgets normally define only a few methods and inherit the rest. Compound 
widgets based on Core will move and resize their children manually in their resd.ze meth- 
od. If the widget is a subclass of Composite or Constraint, the normal geometry management 
facilities manage the position and size of the children. If it is a subclass of Constraint, the 
main widget sets the constraints of the children to control the geometry management process 
by providing a Constraint ].rid. t. d.a3_ ]. ze method. 
A compound widget always needs a dest.ro3, method that destroys the children it created. 
Compound widgets also need a set.._val ues method to manage their resources. 

12.6 Stacking Order 

We promised earlier to say a bit more about how composite or constraint widgets can control 
the stacking order of their children. We noted that this must be done manually, because Xt 
doesn't provide much support for it. This is because most applications do not stack widg- 
ets--the whole concept of geometry management is based on each widget trying to lay out 
its children without stacking them. However, there are applications where it makes sense to 
stack widgets. For example, an application that provides note cards, where each card is a 
widget, would want to stack them showing only the comer of hidden cards. 

"l'When a child of a simple widget calls Xt:NakeGeornet:ryRequest: ( ) because it wants to change its size, Xt:- 
MakeGeometryRequest () always makes the requested changes and returns XtGeometryYes. Therefore, a 
simple widget parent really has no control over its child if the child wants to resize itself. A simple widget cannot 
even tell that the child has resized itself. 
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There is no Core resource for stacking order, and therefore it can't be set with XtSet- 
Values ( ) unless you define the resources in your own widget class. Xt provides no call to 
restack windows; you must use the Xlib functions XConfigureWindow(), XRestack- 
Windows(), XRaiseWindow(), or XLowerWindow(). When a widget suggests a 
stacking order for itself through its query_geometry method, Xt takes care of making the 
required Xlib call if the parent agrees with the change. However, stacking requests of unreal- 
ized widgets have no effect (so stacking order won't be set this way in the initial geometry 
negotiation). Therefore, the most robust method to handle stacking order is for your compos- 
ite widget to make the appropriate Xlib calls directly to change the stacking order of its chil- 
dren. XRestackWindows () is probably the best call to use. Since restacking the win- 
dows doesn't change their requirements for screen space, it shouldn't affect either the parent 
or the children adversely. The appropriate place to call XRestackWindows ( ) depends on 
when you want to change the stacking order. (Note that the stacking change won't become 
visible until the next time Xt is waiting for an event.) 
You can control the initial stacking order of a group of children by creating them in the de- 
sired order. The most recently created widget appears on the bottom. (This is the opposite of 
what you might expect if you know that newly created X windows appears on top of their 
siblings. The difference is due to the way a composite widget maintains its list of children.) 
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13 

Menus, Gadgets, and Cascaded Popups 

This chapter describes how menus work, and several ways to create menu 
widgets. One of these ways involves the use of windowless widgets, or gad- 
gets. This chapter also describes how to use more advanced features of the 
Xt pop-up mechanism, including modal cascades, to implement cascading 
pop-up menus and dialog boxes. 
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13 
Menus, Gadgets, 
and Cascaded Popups 

In Chapter 2, Introduction to the X Toolkit, we show a simple example that pops up a dialog 
box. This chapter is much more thorough in describing the Xt facilities for managing pop 
ups, including both pop-up menus and dialog boxes. 
Although the menus provided by various widget sets vary greatly in the way they look and in 
the way they are used in the application, the underlying Xt facilities for managing them are 
the same. This chapter presents a series of examples based on the Athena widgets that imple- 
ment menus in different ways. While some of the techniques shown are hidden within the 
menu widgets provided in commercial widget sets, it will help you understand menus better 
to see the underlying techniques and issues fully exposed and explored. 
This chapter also discusses cascaded popups--popups that call other popups--and the event 
management necessary for them to shut out other input elsewhere in the application and sys- 
tem. 
Finally, this chapter discusses windowless widgets called gaets, which were originally 
designed to reduce X server memory consumption. Later improvements in the implementa- 
tion of windows in the X server reduce the advantage of gadgets. Their most important use is 
to implement the panes in menu widgets. As an example of a widget that manages gadgets, 
we will show the Athena SimpleMenu widget and its gadget children. 
Also introduced is the object, which is another kind of windowless widget even simpler than 
a gadget. Objects are not usually used in menus, so we will reserve discussion of them until 
Chapter 14, Miscellaneous Toolkit Programming Techniques. 
In this chapter, we use the term menu broadly to refer to any user-interface element that lists 
many options and allows the user to select one or more. A menu might consist of a list of 
commands, only one of which can be selected at a time, or a list of nonexclusive Boolean set- 
tings that can be turned on or off, or a list of exclusive choices (such as the colors or patterns 
for a paint palette). A menu that invokes commands will start in the same state each time, 
while the other two types may have different contents in any particular invocation, showing 
the settings invoked the previous time or all previous times, or a modified list of choices. 
Menus are one of the most important user-interface elements in window-based applications. 
They offer the same feature as push buttons--a way for the user to invoke application func- 
tions or set parameters--but in a more organized and more easily accessible fashion when 
there are more than a few buttons. 
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Figure 13-1. Athena Command widgets in an Athena Box widget, and the same commands as 
a SimpleMenu 

Figure 13-2 compares a menu to a box full of buttons. 
The menu takes up less space because only its title is visible until it is called up.i" As a result, 
you can have more menus than you could have permanent button boxes. Commands can be 
presented in smaller, more closely related groups. The user will spend less time searching for 
the desired command. 
The commands in the menu are also easier to read because they are arranged one per row. 
The commands in the menu may even be easier to invoke because it is more natural to drag 
the mouse up and down than from side to side. And last but not least, menus avoid the worst 
problem with button boxes: when the application is resized, button boxes may place each 
command widget in a different position, making it more difficult for the user to find com- 
mands.:l: 
Some of the applications in the core distribution from MIT use button boxes instead of menus 
because there was no menu widget in the Athena widget set until Release 4. And some of the 
applications that do use menus have implemented them directly with Xlib. 

I Some menus don't even display a title--they simply pop up at the pointer position in response to a particular point- 
er button/keypress combination. This is the behavior of the menus provided by xterm and the system menu of mwm. 
However, this is not very desirable behavior from a user-interface point of view, since it gives the user no visual feed- 
back that a menu is available or how to invoke it. The user needs the manual--something graphical user interfaces 
are designed to avoid. 
:To be fair, there is something to be said for the fact that all the available commands are always visible in an applica- 
tion that uses button boxes. You can invoke a button in a box with just a button click, while in a menu it requires a 
press, a drag, and a release. When there are only a small number of commands, putting the command widgets in a 
box is probably better than using a menu. 
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13.1 Menu Styles and Implementation 

The conventions for the appearance and user interface of menus (look and feel) in widget sets 
probably varies more than any other aspect of the user interface. 
There are several different styles of menus. As we've pointed out earlier, a button box is 
itself a style of menu. However, in this chapter we will be focusing on pop-up 
menus--menus that are not visible until the user presses a pointer button or a key-button 
combination. 
There are several different styles of pop-up menu. Probably the most familiar is the pull- 
down menu popularized by the Apple Macintosh. A pull-down menu has a label permanently 
visible in the application, usually on a menu bar at the top. When the pointer is clicked on 
the label, the menu is displayed below like a window shade, and remains displayed as long as 
the pointer button is depressed. The currently selected item (as indicated by the pointer posi- 
tion within the menu) is highlighted, and is executed when the pointer button is released. 
The variation adopted by Motif and OPEN LOOK (possibly to avoid legal entanglements with 
Apple) is a menu which works just like the Mac menu, but in addition the pointer need not be 
held down to keep the menu displayed. A click on the menu title will display the menu, and 
then a selection can be made with another click. In addition, OPEN LOOK has always had a 
PushPin metaphore whereby menus can be permanently displayed by "pinning" them to the 
desktop. As of version 1.2, Motif also has this capability but calls it "Tear Off'" menus. 
In some cases, selecting an item on the menu or moving off the right side of certain menu 
panes causes a second menu to appear next to the first (usually to the right). This is referred 
to as a cascading menu. (Another type of cascading popup is a dialog box that pops up 
another dialog box.) 
Finally, there is the pure spring-loaded pop-up menu used by many of the standard X clients, 
which displays no menu label, and simply pops up at the pointer position, given the appropri- 
ate key or button press. For example, the menus in xterm pop up when you hold the Control 
key and press the first or second button while the pointer is anywhere in the xterm window. 
We will refer to these menus using the term spring-loaded since the term pop-up is too gen- 
eric. 
One can also imagine many other possible menu styles. For example, an effective user 
interface could be constructed using only horizontal menus, emulating the single-line menu 
popularized by Lotus for its character-based 1-2-3 spreadsheet. Any given button might 
either execute an action, or pop up a lower-level menu, which would overlay (and thus 
appear to replace) the first menu. 
In this chapter, though, we will focus on the two styles of menu you are most likely to 
encounter in X applications: the pull-down menu and the pure spring-loaded pop-up menu. 
In code, the difference between spring-loaded and pull-down menus is primarily the method 
by which the user invokes the menu and where the menu is placed; one menu widget class 
can usually work in either way. 
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All the differences described so far concern user-interface conventions. The Xt specification, 
however, classifies popups using a different criteria--while the menu is popped up, how is 
input dispatched to other parts of the application and to other applications? Also, is the menu 
subject to window management? The three styles are called modeless popups, modal popups, 
and spring-loaded popups. 
Modeless popups are windows that, once popped up, are subject to window manager control, 
and for all intents and purposes act like regular applications in themselves. A help window 
that stayed up, and could be moved and resized like a regular window once popped up, is an 
example of this type of popup. It is referred to as "modeless" because it doesn't put the 
application into a special mode, in which only input to the popup is allowed. 
A modal popup may or may not be visible to the window manager, but it always disables 
user-event processing by the application, except in the popup itself. A dialog box that 
requires the user to enter data or click on a button is an example of a modal popup. Input 
may still be possible to other applications. 

As defined by Xt, a spring-loaded popup is invisible to the window manager and disables 
user input to all windows in all applications, except to the popup itself. The most important 
thing about spring-loaded popups is that they are invoked with a key or pointer button press, 
whereas another type of popup might be invoked as a routine part of application processing, 
or just because the pointer entered a particular window. Note that even though the term 
spring-loaded has been used in two different contexts above, both actually refer to the same 
kinds of widgets. The first use referred to a characteristic user-interface style, and the second 
to a characteristic absence of window management and disabling of input to other applica- 
tions. Throughout this chapter, though, we use the term "spring-loaded popup'" to refer to 
menus that pop up at the pointer position when a mouse button is pressed, such as that used 
by xterm, as opposed to pop-up or pull-down menus. 

13.1.1 

How Menus are Popped Up 

How you create menus in an application differs according to the class of menu widget and 
whether it will be drop-down or spring-loaded. Commercial widget sets are designed to 
make it quite easy to create menus that fit into their user-interlace conventions. As usual, the 
examples in this chapter use the Athena widgets to implement various types of menus. 
Although the procedure for creating menus under the widget set you plan to use may be dif- 
ferent, many of the underlying issues are the same. 

In Section 3.4, a dialog pop up was created by first creating a pop-up shell, and then creating 
the widget to be popped up as a child of the pop-up shell. This procedure is used for some 
menu widgets, but most menu widgets are themselves subclasses of Shell, and therefore no 
separate shell needs to be created. You just create an instance of the menu widget itself, 
using XtVaCreatePopupShell ( ) instead of XtVaCreateManagedWidget (). 

To have a spring-loaded pop up, your application usually adds an action that places the 
widget in the application main window. (Xt has a standard action for popping up a widget, 
but by default it places the widget at the top-left corner of the screen. As a result, you must 
use it in conjunction with an action of your own, which moves the invisible shell widget to 
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the desired location before it is actually popped up.) The application-defaults file should 
supply a translation to specify what event sequence will call up that menu. 
In some cases, a menu widget itself may add actions and translations to the parent so that the 
widget can be popped up in spring-loaded fashion without any application code. In others, 
the widget will add the actions but leave the user or the application writer to define the trans- 
lation that will invoke the action. 
To use a menu in drop-down fashion, you create a Command widget and use its callback to 
pop up the menu, or better still, use a widget specially made to invoke a drop-down menu, 
and tell it the name of the shell to be popped up (which as just mentioned may be the menu 
widget itself). 
Menus differ widely on their conventions for when to pop down. Most menus pop down after 
a choice is made. In this case, the callback invoked to tell the application about the menu 
choice would pop down the widget, or perhaps the menu widget itself would pop itself down 
before calling the chosen item's callback. Some menus pop down whenever the button that 
popped them up is released (for example, xterrn), even if the pointer is outside the menu 
when the button is released. Some pop down whenever the pointer moves out of the menu 
(for example, uwm).f OPEN LOOK menus provide a pushpin that allows the user to keep a 
pop-up menu on the screen, where it will be handy for repeated use. The pushpin looks like a 
thumb tack and has two positions: fastened and loose. 

13.1.2 

Menu Panes 

The style of the items, or panes, in the menus also varies widely. Panes are usually imple- 
mented using one or more subwidgets, or in the case of Motif and the Athena SimpleMenu 
widget, with gadgets, which are windowless objects that can be drawn and managed sepa- 
rately within a widget. There may be several different widgets or gadgets that implement 
menu panes with different input and output semantics. 

If the panes are widgets, they are created with XtVaCreateManagedWidget (), or in 
some menu widgets, by specifying resources of the menu widget, which will then create its 
own panes; how gadgets are created is discussed later in this chapter. 

Figure 13-2 shows menus developed using OSF's Motif and AT&T's OPEN LOOK Toolkit, 
which you can compare and contrast with each other and with the Athena SimpleMenu 
widget shown in Figure 13-1. 

t Most people find it annoying to have menus that pop down when the pointer moves out of them. It is too easy to 
accidentally move outside the menu and have to start all over. All the menus in this chapter pop down the menu 
when the choice is made, or when the button is released outside the menu. 
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Figure 13-2. Menus from the OPEN LOOK and Motif widget sets 

The Athena SimpleMenu widget has rectangular panes that display an identifying string, and 
an optional bitmap before and/or after the string. For example, the bitmap can be used to 
place a checkmark to the left of the label (indicating that an option has been selected and is 
in effect), or an arrow to the right, indicating that selecting this pane will produce a cascad- 
ing submenu. When an item is selected, it is displayed in inverse video. 

Motif menu panes are rectangular. The currently-selected pane is highlighted with a simu- 
lated 3-D shadow. Panes may contain either a string or a bitmap. 

OPEN LOOK menus come with several types of panes, depending on the type of menu item. 
Commands, whether available from menus, or in other control areas, are represented by 
oblong buttons with rounded ends. (Buttons that generate menus or submenus follow their 
label with an arrowhead pointing in the direction where the submenu will appear.) Exclusive 
options are shown as adjacent rectangles, with the one currently chosen highlighted by a dark 
border. Nonexclusive options are displayed in rectangles with a small separation between 
each one. Panes may contain a string or a bitmap, or both. 

However, what all menu widgets have in common is that the application programmer can set 
the label of each pane and the function it invokes. Exactly how to do this varies according to 
the widget set you use. 
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See Appendix A, Athena, OPEN LOOK and Motif, for more information on how Motif and 
OPEN LOOK implement menus. 

13.2 Basic Xt Popup Support 

This section describes how to create and use a menu using the Athena widgets in two differ- 
ent menu styles: spring-loaded and pulldown. The purpose of this exercise is to expose some 
of the issues involved in event management of popups. Seeing how to do the event manage- 
ment explicitly should help you to use popups more effectively. 
The challenge of creating a popup with Box and Command buttons is to make it pop up and 
down at the right times, and to control its event handling to fit the menu style. We will also 
experiment with creating a cascaded menu, in which one menu pane in a main menu invokes 
a submenu. 
Finally, this section describes how to create a menu using the Athena SimpleMenu widget 
and its gadget children. 

13.2.1 

A Spring-loaded Menu: Pointer Grabbing 

A spring-loaded menu should pop up when a button press occurs in a particular widget; 
usually the application's main window. The menu should stay visible as long as the user 
holds down that button, and disappear when the button is released. If the button is released in 
a menu pane, the function registered for that pane should be invoked. If the button is 
released outside the menu, no function should be invoked but the menu should still be 
popped down. 
The only tricky part of implementing a spring-loaded menu is getting the menu to pop down 
when the button is released outside the menu. Since this occurs outside the menu and possi- 
bly outside the application, the X server will not send the button release event to the applica- 
tion unless a grab is in effect. Normally, user events are sent to the window that contains the 
pointer. But after an application makes a grab, the X server sends all events of particular 
types to the window that made the grab, even if the pointer is no longer in the window. 
The X server defines several types of grab: keyboard grabs, pointer grabs, and server grabs. 
Keyboard and pointer grabs control only input from the indicated device, while server grabs 
make the server act on requests from one application exclusively. (Server grabs are mainly 
used by window managers.) Pointer grabs are used for controlling events in popups when a 
pointer button pops up the popup, and keyboard grabs are used when a key press pops up the 
popup. We will discuss pointer grabs since keyboard grabs are analogous (and keyboard-trig- 
gered popups are less common). 
There are two types of pointer grabs: passive grabs and active grabs. An active grab is 
invoked directly with the Xt function XtzGrabPof_ntzer (). This function tells the server 
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that you want the grab to begin right away and to continue until specifically released with 
Xt:UngrabPoint:er (). Active grabs are not normally used for popups.'l" 
A passive grab tells the server that you want a grab to begin when a certain key or button 
combination is pressed in a certain window (the combination that is to pop up the popup). 
The grab continues until the button in the combination is released. This is perfect for menus 
because we need the grab only until the button is released. (Also, as you'll see in the section 
on pulldown menus, you can register several passive grabs for the same key-button combina- 
tion as long as each grab is initiated by a press in a different window. This technique lets you 
have as many pulldown menus as you want. Since spring-loaded popups are generally 
invoked by a press in the same window--the main window of the application--you will 
need to use a different key-button combination for each different menu.) 
Passive grabs of a key or button and active grabs of the pointer or the keyboard we will call 
global grabs, since they affect not only this application but prevent distribution of the 
grabbed events to other applications running on the same server. This terminology is to dis- 
tinguish the global grab from the effects of Xt's local grab mode, which simulates a global 
grab but requires no call to the server and affects only the distribution of events within the 
application. The Xt grab mode cannot commandeer events that occur outside the application 
like a global grab can. When an Xt grab is in effect, Xt redirects user events to the popups 
even if they occur somewhere else in the application. (Non-user events continue to be 
dispatched to widgets so that they can redraw themselves.) 
The Xt grab mode can be either exclusive or nonexclusive. Exclusive and nonexclusive Xt 
grabs differ only when a popup has popped up another popup--a so-called cascaded popup. 
An exclusive Xt grab redirects all user events that occur within the application to the latest 
popup in the cascade. A nonexclusive Xt grab redirects events to whichever popup the 
pointer is in, or the latest popup if the pointer is outside all the popups (but still in the appli- 
cation). 
Here are examples of the two kinds of Xt grab modes. Consider an application that pops up a 
dialog box to get a filename from the user. The application wants to read the file. If the file 
can't be opened, the application pops up another dialog telling this to the user. This error 
popup takes no input, so input is still desired in the filename entry popup. This situation calls 
for a nonexclusive grab. By contrast, consider an application that uses the same filename 
entry popup to save a file. If the file exists, it would pop up a dialog that would ask whether 
the existing file should be overwritten. This popup must be answered before a new filename 
is chosen. This situation would call for an exclusive grab. In brief, an exclusive grab con- 
strains input to the the latest widget in the cascade, while a nonexclusive grab allows input to 
any widget in the cascade. We'll talk more about the Xt grab mode in Section 13.2.3, when 
we talk about popup cascades. 

%One reason that XtGrabPointer ( ) is rarely used for popups is that it requires that the window that will receive 
the grabbed events be visible. This is often not the case. In a menu, for example, the window that you want to grab 
the events may be hidden by the menu panes even when the menu is popped up. Another reason is that you need to 
call XtUngrabPointer ( ) to release the grab when finished. Passive grabs match the task better. 
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Example 13-1. xmenul : complete code (continued) 
*/ 
#include <Xll/Xaw/C(mmand. h> 
#include <XII/Xaw/Box. h> 
#include <XII/Xaw/Label. h> 
/* 
* The popup shell ID is global because both dialog and pshell 
* are needed in the dialogDone callback, and both can't be 
* passed in without creating a structure. 
*/ 
Widget pshell; 
/ *ARGSUSED* / 
void PlaceMenu(w, event) 
Widget w; 
XButtonEvent *event; 
{ 
/* should make sure coordinates allow menu to fit on screen */ 
/* move sulmnu shell to slightly left and above button 
* press position */ 
XtVaSetValues (pshell, 
XtNx, event->x_root - i0, 
XtNy, event->y_root- i0, 
NULL) ; 
} 
/* 
* quit button callback function 
*/ 
/ *ARGSUSED* / 
void Quit(w, client_data, call_data) 
Widget w; 
XtPointer client_data, call_data; 
{ 
exit (0) ; 
} 
/* 
* menu pane button callback function 
*/ 
/ *ARGSUSED* / 
void paneChosen(w, client_data, call_data) 
Widget w; 
XtPointer client_data; /* cast to pane_number */ 
XtPointer call_data; 
{ 
int pane_number = (int) client_data; 
printf (" Pane %d chosen. \n", pane_number) ; 
XtPopdown (pshell) ; 
} 
main (argc, argv) 
int argc; 
char **argv; 
{ 
XtAppContext app_context; 
Widget topLevel, box, quit, label, menulabel, menubox, 
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Example 13-1. xmenul: complete code (continued) 
menupane [ 10 ] ; 
int i; 
String buf[50 ] ; 
static XtActionsRec trial_actions [ ] = { 
{ "placeMenu", PlaceMenu}, 
}; 
XtSetLanguageProc (NULL, (XtLanguageProc)NULL, NULL) ; 
topLevel = XtVaAppInitialize ( 
&app_context, /* Application context */ 
"XMenul", /* application class name */ 
NULL, 0, /* conmand line option list */ 
&argc, argv, /* cornand line args */ 
NULL, /* for missing app-defaults file */ 
NULL) ; /* terminate varargs list */ 
box = XtCreateManagedWidget ( 
"box", /* widget name */ 
boXWidgetClass, /* widget class */ 
topLevel, /* parent widget */ 
NULL, /* argument list */ 
0 /* arglist size */ 
); 
label = XtCreateManagedWidget ( 
"label", /* widget name */ 
labelWidgetClass, /* widget class */ 
box, /* parent widget */ 
NULL, /* argument list */ 
0 /* arglist size */ 
); 
quit = XtCreateManagedWidget ( 
"quit", /* widget name */ 
conmandWidgetClass, /* widget class */ 
box, /* parent widget */ 
NULL, /* argument list */ 
0 /* arglist size */ 
); 
pshell = XtCreatePopupShell ( 
"pshell ", 
transientShel iWidgetClass, 
topLevel, 
NULL, 
0 
); 
menubox = XtCreateManagedWidget ( 
"menubox", /* widget name */ 
boXWidgetClass, /* widget class */ 
pshell, /* parent widget */ 
NULL, /* argument list */ 
0 /* arglist size */ 
); 
menulabel = XtCreateManagedWidget ( 
"menulabel", /* widget name */ 
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We are replacing rather than overriding this widget's translations because it is a Label widget 
and has no default translations. 
The menu panes are Command widgets, but we need to adjust their event response so that 
they will be triggered on a button release with no corresponding press (since the press that 
popped up the menu occurred in the application main window). We are replacing their trans- 
lations to get rid of the translation for ButtonPress (which would still be present if we 
used the #augment directive, and we would have to create an action that did nothing in 
order to replace it with #override). The translation for ButtonRelease (abbreviated 
BtnUp in the translation table) calls all the actions that usually occur in Command widgets 
with both press and release. 
Perhaps least obvious is the translation we have added to pop down the menu when the 
pointer button is released outside the menu. As mentioned earlier, Xt makes a passive global 
pointer grab on the popup shell (pshell) in the XtMenuPopup() action. When the 
pointer is inside the menu, the Command widgets intercept these grabbed events, because 
they are descendants of pshell and they have a translation for ButtonRelease events. 
This invokes the actions in the selected Command widget. But when the pointer is outside 
the menu, the grabbed events are sent directly to the widget that was specified in the grab 
call, namely pshell. Therefore, the translation to pop down the menu on button release 
must be added to pshell. (Again, this translation table is simply replaced because the 
popup shell normally has no translations.) 

13.2.2 

A Pulldown Menu 

What are the desired characteristics of a pulidown menu? There is a Command widget or the 
like permanently visible in the application, with a label indicating some common characteris- 
tic of the items in the menu. When a button is pressed in this widget, the menu should pop up 
on or just below the button. Dragging the pointer down through the menu with the button 
still held should highlight the entry that is pointed to. Releasing the button in an entry should 
invoke or set that entry and pop down the menu. Moving out of the menu should not change 
this behavior, except that if the button is released anywhere outside of a menu pane, the menu 
should pop down without executing any entry. 

If you compile and run xmenu2 you can try out this style of menu. The appearance of this 
application is shown in Figure 13-4. 

Invoking a menu as a pulldown is a simple enhancement of the spring-loaded invocation 
method just shown. We can do everything exactly the same as in the spring-loaded example, 
except that a pulldown menu should appear just below the pressme widget, not at the posi- 
tion of the pointer. Therefore, all we need to change is the placement code. However, since 
the coordinates in the event are not necessary for placing the popups, we can use a callback 
function instead of an action to place the popup. (In general, it is better to use an existing 
callback than to add an action to do the same thing.) 
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13.2.3 Cascaded Menus 

A cascaded menu is a menu in which one or more panes do not invoke functions but instead 
bring up additional menus. 

The techniques used to bring up cascaded menus can also be used to have dialog boxes bring 
up other dialog boxes. However, cascaded menus are more challenging because they rely on 
the passive global pointer grab to receive the ButtonRelease event that occurs outside 
the menu and application. 

You can implement a cascaded menu the same way for both spring-loaded and pulldown 
menus simply by adding to the code we've already written to implement a single menu. 
We'll show you xmenu5, the spring-loaded version, since it is slightly shorter. (xmenu4 is the 
equivalent pulldown version.) Both are included in the example source code. In this 
example, only one menu pane will be used to invoke a submenu. However, this technique 
can be generalized to have additional panes bring up additional submenus. 

First, let's describe exactly how we expect the cascaded menu to work. Figure 13-5 shows 
both menus popped up. (Compile the program and try it.) 

MAIN MENU 

View Next 
View Previous 
Delete 
Move 
UnmBrk 

Copg To ==> SUB MENU 
View In New Xnews folder 
Replg Xt folder 
Forward Xlib folder 
Use As Comp Xconsortlum 

Xaw folder 
Drafts folder 
Misc folder 

Personal fold 
Xprotocol fol 
To Do List 

Figure 13-5. xmenu5: cascaded spring-loaded menus 

The main menu works as described above. However, one of the panes--the one that bnngs 
up the submenu--has an arrow pointing to the right after its label. This pane does not 
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main menu will get pointer events if you use grab mode XtGrabNonexclusive. Because 
of the logic that pops down the submenu when the pointer leaves it through the portion 
adjoining the main menu, you can see this difference only if you move out through another 
part of the submenu and then around into the main menu again. (In the example code distri- 
bution, xrnenuS.c uses XtGrabNonexclusive and xrnenu4.c uses XtGrabExclus ive, 
so that you can compare the results of these two flags.) 
The user-interface conventions for a particular widget set usually specify which kinds of pop- 
ups should have exclusive grabs and which nonexclusive. Note that the effect of these two 
grab modes is the same unless there is more than one popup widget in a cascade visible. 
CheckRightAndPopupSubmenu places the submenu itself (instead of using a separate 
action) because the menu should be placed only when it is first popped up. If the placement 
code were a separate action, it would be called every time a LeaveWindow event arrived, 
even if not through the correct border of the widget. (Remember that this code is in an action 
rather than a callback because it uses the contents of the event.) 

The translation portion of the app-defaults file for xrnenu5 is shown in Example 13-6. 

Example 13-6. XMenu5: translation portion of app-defaults file 
! 
! Appearance resources 
! 
*menupane5. label: Copy To ==> 
(other appearance resources not shown) 
! 
: Translation resources 
! 
: popping down both menus 
*pshell. translations: \ 
<BtnUp>: XtMenuPopdown (subshell) XtMenuPopdown (pshell) 
! popping up main menu 
*label. translations : \ 
<BtnIk]wn>: placeMenu ( ) XtMenuPopup (pshell) 
! 
! popping down sulmnenu 
*menubox.menupane5. translations: \ 
<LeaveWindow>: checkRightAndPopupSulmne_nu ( ) 
! 
! Main Menu translations 
*menubox. Ccmnand. translations: \ 
<EnterWindow>: highlight ( ) \n\ 
<LeaveWindow>: reset ( ) \n\ 
<BtnUp>: set ( ) notify ( ) unset ( ) 
! Sub Menu translations 
* subbox, translations: \ 
<LeaveWindow>: popdu (subbox) 
*subbox. Ccmnand. translations: \ 
<EnterWindow>: highlight ( ) \n\ 
<LeaveWindow>: reset ( ) \n\ 
<BtnUp>: set() notify() unset() 
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13.2.4 Using the SimpleMenu Widget 

Athena also includes a real menu widget: the SimpleMenu widget. The internals of this 
widget and its children, which are gadgets, are described later. This section describes a 
simple application that uses the SimpleMenu widget. 
Athena supplies three types of panes to be used with the SimpleMenu widget: SmeBSB (an 
entry composed of a bitmap, a string, and another bitmap), SmeLine (a horizontal line 
between entries), and Sme (a blank entry). The SimpleMenu widget is itself a subclass of the 
popup shell widget, and therefore no separate popup shell needs to be created. 
Athena also provides a MenuButton widget, which is a subclass of Command with built-in 
placement and popup code. Using a MenuButton to invoke a menu makes it even simpler to 
implement a pulldown menu, since the popup and placement code can be eliminated from the 
application. 

The xmenu7 application shown in Example 13-7 creates a SimpleMenu widget with panes of 
all three types. The menu is invoked in pulldown style using the MenuButton widget.$ 

As an additional enhancement, the menu marks or unmarks each item when it is selected in 
addition to calling a callback function. This iteration marks entries with the X logo, which is 
available as a standard bitmap in/usr/include/Xll/bitmaps (on UNIX systems). 

Figure 13-6 shows the appearance of the program. 

Click here for menu 

Sho Scrollbar 
Enable Reverse Video 
Enable Bell 

Cop 
Unmrk 

Replg 
Forward 
Print 

Figure 13-6. xmenu7: a menu using the Athena SimpleMenu widget 

'This example was written by Chris Peterson of MIT Project Athena and modified only slightly by the authors. 
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Example 13-7. xmenu7: using the SimpleMenu widget and its children 
/* xme_u7.c */ 
#include <stdio.h> 
#include <XII/Intrinsic .h> 
#include <XII/StringDefs .h> 
#include <XII/bitmaps/xlogol6> 
#include <XI 1/Xaw/MenuBut ton. h> 
#include <XI 1/Xaw/SimpleMenu. h> 
#include <XII/Xaw/SmeBSB. h> 
#include <XI 1/Xaw/SmeLine. h> 
#define NUM_MI_ITEMS 12 
static String menu_entry_names [ ] = { 
"quit" , 
"itestl" , 
"item2" , 
"itera3" , 
"line" , 
"item5", 
"iten6", 
"iten7", 
"blank", 
"menul" , 
"rnenu3" , 
); 
static Boolean status [NUM_MENU_ITEMS ] ; 
static Pixmap mark; 
/* ARGSUSED * / 
static void 
MenuSelect(w, client_data, garbage) 
Widget w; 
XtPointer client_data; 
XtPointer garbage; /* call_data */ 
{ 
int pane_num = (int) client_data; 
printf("Menu item %s has been selected. \n" , XtName(w)) ; 
if (panenum == 0) /* quit selected. */ 
exit (0) ; 
if (status [pane_num ] ) 
XtVaSetValues (w, 
XtNleftBitmap, None, 
NULL) ; 
else 
XtVaSetValues (w, 
XtNleftBitmap, mark, 
NULL) ; 
status [panenum ] = : status [panenum ] ; 
} 
void 
main (argc, argv) 
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menu pane gadget calls the DolncorporateNewMail callback function. The Xt- 
Naccelerators resource for the SimpleMenu widget itself (not the gadgets) maps a 
Meta-I key event into a call to the XmhlncorporateNewVlail global action. Xmh- 
IncorporateNewNail then calls DolncorporateNewNail. This use of accelerators 
depends on having both a callback and an action form of each function. 

13.2.5 

Delayed Popup Creation 

As we've seen, a popup may consist of a single widget, or it may be a shell widget which 
contains a composite widget which contains a number of children. In the latter case, creating 
all those widgets (or gadgets) takes time. It may be beneficial to create those widgets using 
idle time in the application instead of delaying startup. In either case, it may make sense to 
create the popup only when it is needed, to minimize wasted resources. 
If your goal is to speed startup, and you want all menus created even if some are never used, 
you can register a work procedure to create each popup, as described in Section 8.5. As you 
may recall, a work procedure uses idle time in the application to call a function, which must 
return swiftly. If you use this technique, you add one work procedure for each popup you 
need to create, and you need to add code to make sure that the popup has been created before 
the user is allowed to use it. 
If your goal is to create only the required popups, you can create the popup in a callback 
function or action routine that you have registered to place or pop up the popup. In this case, 
you would have a static variable in the callback or action to make sure that the popup widg- 
ets are only created the first time the popup is popped up. You need to have created the 
popup shell before this can work. 
There is also another way to create only the required popups. Shell widgets have an Xt- 
NcreatePolOuloChildProc resource which you can set to a function that creates the 
Shell's children. See XtCreatePolOuloChildProc (2) in Volume Five, X Toolkit lntrin- 
sics Reference Manual, for the calling sequence of this function type. The Xt specification 
does not say whether an XtCreatePopupChildProc is called just once when the shell is 
first popped up or every time it is popped up. But the MIT implementation of Xt calls it 
every time the shell is popped up, so you will again need a static variable to make sure the 
children are only created once. 

13.3 About Dialog Boxes 

Although we have been talking so far exclusively about menus, much that has been said is 
also true of dialog boxes. Both menus and dialog boxes that get user input usually need to 
get that input before other application functions can be invoked. Of course, one way to dis- 
able all other application functions is to make all other widgets insensitive with XtSet- 
Sensitive () (passing it False). Setting the sensitivity of one common ancestor does 
this efficiently, but even this is too slow because all the widgets redraw themselves dimmed 
or grayed. It is much faster to use a global grab. Unlike menus, which require the global 
grab in order to get button release events outside the application so they can pop down 
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properly, dialog boxes do not, strictly speaking, need a grab. But they sometimes make the 
grab anyway to disable other application functions. 
Dialog boxes can also invoke other dialog boxes. For example, a dialog box that gets input 
might check the validity of the input before popping down the dialog, and if incorrect, pop up 
a message telling the user the problem with the input. Cascaded dialog boxes are imple- 
mented the same way as cascaded menus. Note that, as a general rule, sub-dialog boxes are 
popped up with grab mode XtGrabExclusive, which means that the user must satisfy the 
most deeply nested dialog first. However, it is often desirable to leave a Help dialog on the 
screen until after the dialog it provides help for has been removed. 
Some popups do not need to disable other application functions. For example, imagine a dia- 
log box that informed the user of some fact without requiring confirmation. This kind of 
popup would be popped up with grab mode XtGrabNone, allowing the user to continue 
with other application functions. 
We pointed out earlier that the built-in callback functions for popping up a widget are not 
useful for menus because they make no passive global pointer grab. However, they come in 
handy for dialog boxes. The functions XtCallbackNone(). XtCallback- 
Exclusive (), and XtCallbackNonexclusive ( ) can be used to pop up dialog boxes 
as long as the position of the dialog box need not depend on information in an event. 
We haven't shown how to use Xt's standard callback for popping down a widget: Xt- 
CallbackPopdown(). Instead of calling XtPopdown() in the callback functions for 
each menu entry, we can add XtCallbackPopdown ( ) to the callback list after the exist- 
ing callback function. XtCallbackPopdown() requires an XtPopdownId structure to 
be passed as the client_data argument. This structure must contain the popup shell and 
the widget that invoked the popup (the MenuButton or Command widget). 
All three of the standard popup callbacks set the invoking widget to insensitive mode before 
popping up the widget. XtCallbackPopdown() resets the invoking widget to sensitive 
mode. Therefore, if you use XtCallbackNone (), XtCallbackNonexclusive (), or 
XtCallbackExclusive ( ) without also using XtCallbackPopdown ( ), remember to 
set the widget to sensitive mode yourself. This feature is useless but also harmless when the 
popup is spring-loaded, because the invoking widget is often the main application window 
and that widget rarely responds to sensitivity. 
In certain rare cases, you may want to use XtAddGrab ( ) and XtRemoveGrab ( ) directly 
to append a widget to or remove a widget from the current popup cascade. These functions 
are called internally by the Xt facilities that pop widgets up and down, and should not be nec- 
essary on their own. Note that these functions never make a request to the server to start or 
release a passive global pointer grab--they affect only Xt's internal event dispatching. (The 
functions XtGrabKey ( ), XtGrabKeyboard (), XtGrabButton (), and XtGrab- 
Pointer(), however, do initiate global grabs. These functions are described in Chapter 
14, Miscellaneous Toolkit Programming Techniques.) 
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13.4 Gadgets 

When an application includes many different menus with many fields each, the server mem- 
ory consumption of having separate widgets for every menu pane was once thought to be a 
problem. So the window-less widget, called a gadget, was invented. A gadget depends on 
special behavior of its parent to get events and operate much like a widget. (Gadgets also 
consume slightly less client-side memory.) A gadget is fully configurable using the resource 
database just like a widget, and can have its own callback list. 
Now that the server implementation has been improved, the memory consumption of a win- 
dow is much less significant. And gadgets, can actually reduce performance. In particular, 
the way OSF implemented Motif PushButtonGadgets greatly increases network traffic during 
the crucial user-interaction phase of the application. This is because the Motif PushButton- 
Gadget parent requires MotionNotify events to track whether the pointer has entered or 
left a gadget (since gadgets have no window to cause EnterNotify events). These 
Mot ion_Not i fy events allow the gadget to highlight its border when the pointer enters, just 
like a regular widget. 
This network traffic problem is much more serious than the memory problem gadgets were 
originally thought to improve. Therefore, gadgets should be avoided in uses where they 
cause this problem. 
Gadgets also have other limitations. Gadgets have to draw on their parent's window, and 
they share this space with the parent and with all other gadget children. The gadgets and the 
parent must agree to draw in certain areas only. For this reason, gadgets must be used with a 
special composite widget parent that is prepared to manage them properly. 
The Athena SimpleMenu widget is such a parent. It is a composite widget designed to man- 
age gadget children. The gadgets provided by are Sme, SmeBSB, and SmeLine (where Sme 
stands for Simple Menu Entry). These provide a blank entry (and generic menu entry super- 
class), an entry which can contain a bitmap, a string, and another bitmap (thus BSB), and an 
entry that draws a horizontal line. We will use and describe this widget and these gadgets 
both to show how menu widgets are built and to demonstrate how the parent and the gadgets 
work together. 
Gadgets do not handle events automatically as widgets do, and because they have no win- 
dows, the server does not handle overlapping between them. This places certain demands on 
the parent. All the gadgets that are children of a particular parent share that parent's window. 
The parent is responsible for coordinating the gadget children, telling them about events by 
calling their functions. Therefore, the composite widget that manages a group of gadgets 
must be specially designed for that purpose, not a general-purpose composite or constraint 
widget such as Box or Form. It is possible for a composite widget to manage both gadget and 
widget children, but its code has to be more involved to do this. 
Like normal widgets, gadgets provide their own code to redraw themselves in their expose 
method. However, since gadgets do not receive events, they depend on the parent to directly 
call their expose method. The parent keeps track of the geometry of each child, and when 
the parent's expose method is called, this method calculates whether the area exposed over- 
laps any of the gadget children. If the area exposed does overlap a gadget, the parent's 
expose method calls that gadget's expose method, which redraws the area. 
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A gadget's actions also have to work differently from widget actions because of the fact that 
gadgets don't get events. A gadget defines its actions as methods--as fields in its class part 
structure-a-instead of in an action list and translation table. It initializes these fields directly 
to pointers to functions during class initialization. The parent widget has corresponding 
actions that are defined and operate like normal actions, except that they determine which 
gadget the event that invoked the action occurred in and call the gadget method correspond- 
ing to that action. In other words, the parent has actions that operate the gadget children. 

One weakness of a menu composed of gadget panes is that gadgets cannot have an accelera- 
tor table. Therefore, accelerators cannot be used to provide a keyboard equivalent that would 
invoke each menu pane. 

The parent of gadgets has to position the gadget children so that they do not overlap, or take 
care of the consequences if they do overlap. Since the gadgets draw on the parent's window, 
if they did overlap they would draw over each other's graphics, with unpredictable results. 
The parent would have to calculate the area of overlap between two gadgets, and clear this 
area before letting one of the gadgets draw itself. (A gadget could clear its own area before 
drawing, but this would be unnecessary in many cases, and would cause flashing.) 

Gadgets are subclasses of RectObj, one of the invisible superclasses of Core that we have so 
far ignored because for widgets it is safe to assume that Core is the top of the widget class 
hierarchy.t" The actual class hierarchy leading up to Core is shown in Figure 13-7. 

Object i defines callback handling 
! 
unnamed class  defines window attribute 
resources 
! 
Core  packages superclasses for 
inheritance by widgets 

Figure 13-7. Class hierarchy derivation of Core 

The "unnamed class" actually has a name (WindowObj) but this class is intentionally undo- 
cumented in the Xt specification so that its characteristics can be changed in later releases 
without compatibility problems. You should never create subclasses directly from the 
unnamed class. 
The superclasses of Core are not real classes in the sense that they do not play by all the rules 
we have described in Chapter 6, Inside a Widget. For one thing, each shares what we call the 
Core class structure instead of adding its own part structure. Applications are never intended 
to create instances of these superclasses--they are really just part of the implementation of 

"tOnly the header files for RectObj are public, so that you can write and compile gadgets. 
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The Athena menu pane gadgets are implemented in two class levels: 

Sme (Simple Menu Entry) defines the callback for an entry, the actions to highlight, 
unhighlight, and notify, and the code that allows subclasses to inherit or replace these 
actions (because they are defined as methods). The actual functions for highlight and 
unhighlight are empty, while the notify action calls the callback. The expose method of 
this gadget is also empty. This gadget can be used by itself to create a blank entry. 

SmeBSB and SmeLine are each subclasses of Sme. SmeLine replaces only the expose 
method of its superclass. SmeBSB replaces both the expose method and the highlight 
and unhighlight actions of the superclass. (Sme can be subclassed to create new types of 
menu entries.) 

The following sections describe both Sme and SmeBSB. 

13.4.2 

Private Header File 

The private header file for a gadget is identical in format to the private header file for a 
widget. It defines a class part structure for this class of gadget and then a complete class 
structure including the class parts of superclasses and this class. The only difference is that a 
gadget inherits its features from Object and RectObj, whereas a widget inherits from Core. 
Example 13-9 shows the complete class structure of the Athena Sme gadget. 

Example 13-9. Sme gadget: class part and complete class structure declaration 
typedef struct _SmeClassPart { 
void (*highlight) () ; 
void (*unhighlight) ( ) ; 
void (*notify) () ; 
XtPointer extension; 
} SmeClassPart; 
/* Full class record declaration */ 
typedef struct _SmeClassRec { 
RectObj Clas sPart rect_class; 
SmeClassPart sme_class; 
} SmeClassRec; 
#define XtInheritHighlight ((_XawEntryVoidFunc) _XtInherit) 
#define XtInheritUnhighlight XtInheritHighlight 
#define Xt InheritNoti fy Xt InheritHighlight 
Notice that the complete class structure declaration does not include the class part for the 
Object class, even though it is a superclass. This is because all the superclasses of Core share 
the same class part structure. 
The class part structure for Sme defines three methods--these are essentially the gadget's 
actions, but they will be invoked by the gadget parent's actions, not directly by Xt. The 
extens'i on field allows fields to be added to this structure in a future version while retain- 
ing binary compatibility. In a future version this field could be changed to point to an exten- 
sion structure. 
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all the geometry management code in addition to code for managing events for the gadgets. 
We'll concentrate just on the code that manages events for the gadgets, since the geometry 
management code is described in Chapter 12, Geometry Management. 

Let's begin with the expose method. SimpleMenu's expose method does no drawing of 
its own. It simply calls the expose methods of the gadget children. However, it compares 
the region passed into its expose method to determine which gadgets need redrawing. 
Example 13-11 shows SimpleMenu's expose method. 

Example 13-11. SimpleMenu: expose method calling gadget children's expose methods 
#define ForAllChildren(sr, childP) \ 
for ((childP) = (SmeObject *) (srmq)->composite.children ; \ 
(childP) < (SmeObject *) ( (sr)->ccposite.children + \ 
(smw)->ccposite.nun%_children); (childP)++) 

/* ARGSUSED * / 
static void 
Redisplay(w, event, region) 
Widget w; 
XEvent * event; 
Region region; 
{ 
SimpleMenuWidget srmq = (SimpleMenuWidget) w; 
SmeObject * entry; 
SmeObj ectClass class; 

if (region == NKILL) 
XClearWindow(XtDisplay (w), XtWindow(w) ) ; 

/* 
* Check and Paint each of the entries - including the label. 
*/ 

ForAllChildren(srmq, entry) { 
if (:XtIsManaged ((Widget) *entry)) 
continue; 

if (region l= NULL) 
switch(XRectInRegion(region, (int) (*entry)->rectangle.x, 
(int) (*entry)->rectangle.y, 
(unsigned int) (*entry)->rectangle.width, 
(unsigned int) (*entry)->rectangle.height)) { 
case RectangleIn: 
case RectanglePart: 
break; 
default: 
continue; 
} 
class = (SmeObjectClass) (*entry)->object.widget_class; 

if (class->rect_class.expse != 
(class->rect_class.expse)((Widget) *entry, NLK/, NULL); 

Note that this expose method is also called from elsewhere in the widget code (specifically, 
from the resize and geometry, manager methods) to redraw the gadgets. In these 
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cases, the region passed in is set to CrLL, and the method clears its window and redraws all 
the gadgets. 
Also note how this expose method invokes the expose methods of its children. All 
expose methods (and in fact all methods) are stored in the class structure, not the instance 
structure. Composite widgets keep only a list of the instance structures of their children. 
However, one field in each instance structure points to the class structure for that child. This 
is the widget_class field of the Object instance part.% In this example, the entz3z 
counter variable is a pointer to the gadget ID (opaque pointer to the instance structure) of one 
of the children. Another variable, class, declared as a pointer to the SmeObjectClass 
class structure (the expected class of the children), is set to the widget_class field in the 
instance structure of one of the children. Then the expose field of this class structure is 
checked to see if it is LL, and if not it is invoked. 

Note that the class of the children is hardcoded in this method. This widget can manage only 
Sme widgets and its subclasses. 

The resize method of SimpleMenu must resize the children when it is resized itself. 
(Actually, this is unlikely, since the SimpleMenu widget itself is a subclass of Shell and is 
therefore not managed by any parent.) This method is invoked only when the user resizes the 
menu using the window manager. Since this widget has the authority to determine the geom- 
etry of its children, it can simply resize them. This particular resize method (shown in 
Example 13-12) simply sets their width to be the same as its own. 

Example 13-12. SimpleMenu: resize method 
static void 
Resize (w) 
Widget w; 
{ 
SimpleMenuWidget stow = (SimpleMenuWidget) w; 
SmeObject * entry; 
if (!XtIsRealized(w) ) return; 
ForAllChildren(smw, entry) /* reset width of all entries. */ 
if (XtIsManaged((Widget) *entry)) 
(*entry) ->rectangle.width = smw->core.width; 
Redisplay(w, (XEvent *) N[/IL, (Region) N[/IL); 
Notice that this resize method invokes the expose method (Redisplay) because the 
gadgets don't have resize methods, and will not redraw themselves in response to their 
size change.:l: 

%The Core instance part structure (not complete) is the concatenation of the instance parts of the three superclasses 
Object, RectObj, and the unnamed class. Therefore, it also includes a widget_class field. Since composite 
widgets do not normally need to invoke the methods of their children, you shouldn't need to access this field. 
The gadget children could have res i ze methods, which would be called by the parent's resize method The gad- 
get's resize methods would simply call their expose method. However, this does exactly the same thing as the 
code shown while being more complicated. 
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Now let's look at SimpleMenu's actions. Their only purpose is to call the gadgets' actions 
when the appropriate events arrive. These actions are added in the usual way: they are 
declared at the top of the .c file, then registered with an action list that is entered into the 
class structure initialization, and then defined. One of the three actions is shown in Example 
13-13. 

Example 13-13. SimpleMenu: the Notify action routine 
/* ARGSUSED */ 
static void 
Notify(w, event, params, num_params) 
Widget w; 
XEvent * event; 
String * params; 
Cardinal * num_params; 
{ 
SimpleMenuWidget smw = (SimpleMenuWidget) w; 
SmeObject entry = smw->simple_menu, entry_set; 
SmeObjectClass class; 

if ( (entry == NULL) II !XtIsSensitive((Widget) entry) ) 
return; 

class = (SmeObjectClass) entry->object.widget_class; 
(class->sme_class .notify) ((Widget) entry ) ; 

This action determines whether the chosen entry is sensitive and, if so, calls the notify 
method of that gadget. As described above in the section on the gadget children, gadgets 
define their actions as methods so that they can conveniently be called by their parent. Since 
these methods are stored in the class structure not the instance structure, this is done using 
the technique described above for the expose method. 

Although not critical to its handling of gadgets, SimpleMenu does one more interesting thing. 
It registers the PositionMenuAction action in the global application action list (as 
opposed to the internal widget action list) so that the application or app-defaults file can refer 
to this action in translation tables without needing to register the action. This action can be 
triggered by any type of event in the widget and positions the menu according to data in the 
event type. (SimpleMenu has a resource that controls whether this placement process makes 
sure that the menu is not off the screen.) 

A widget can add an action to the global action list by calling XtAddAction ( ) just like an 
application would, but from its class_initialize method. 
Any composite widget that is capable of managing gadgets must declare a Composite exten- 
sion structure in the .c file and set the accepts_obj ects field of that structure to True. 
It must then set the pointer to the extension structure into the Composite class part structure 
in the class_part_initialize method. Extension structures were introduced in 
Chapter 6, Inside a Widget, and are discussed further in Chapter 14, Miscellaneous Toolkit 
Programming Techniques. Example 13-14 shows this code from SimpleMenu.c. 

418 

X Toolkit Intrinsics Programming Manual, Athena Edition 



14 

Miscellaneous Toolkit 
Programming Techniques 

This chapter describes various Xt functions that have not been treated else- 
where in the book. 
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14 
Miscellaneous Toolkit 
Programming Techniques 

This chapter discusses various Xt facilities that didn't fit neatly into any other chapter. Many 
of them are functions provided mostly because Xt uses them internally, and they are unlikely 
to be useful in application or widget code. Some of them are quite important for accomplish- 
ing certain tasks. You should scan the contents of this chapter to familiarize yourself with 
these facilities so that you will be aware of them. 
The topics covered are errors and warning messages, objects, a description of all of Xt's mac- 
ros and functions for getting information, the Core accept_focus method, how to inter- 
pret key events, Xt's facilities for memory management, making global grabs, file finding 
and internationalization, multiple application contexts, multiple top-level shells, and con- 
necting to multiple servers. 

14.1 

Errors and Warnings 

There are several broad categories of errors that may occur in Xt applications. One is the X 
server error, which is a form of event that tells the client that some parameter in an earlier 
request was illegal, or that no more server memory is available. A second is the connection 
failure error generated by Xlib when the connection with the server fails (usually due to a 
system crash or network interruption). Xlib provides the XSetErrorHandler() and 
XSetIOErrorHandler() functions to allow the application to provide a routine to 
handle these two types of errors. Xt provides no interface to these routines--Toolkit applica- 
tions must use the Xlib routines to customize these error handlers (Xlib uses default error 
handlers when the application does not use these routines to specify them). For a description 
of these error handlers and the routines for changing them, see Volume One, Xlib Program- 
ruing Manual. 
A third category is made up of error and warning messages that Xt reports when function 
parameters are specified improperly, when a translation is incorrectly specified, and for many 
other reasons. For a complete listing of all errors and warnings that can be generated by Xt, 
see Volume Five, X Toolkit Intrinsics Reference Manual, Appendix D, Standard Errors and 
Warnings. Xt provides separate parallel routines for errors and for warnings. The difference 
between Xt errors and Xt warnings is that errors are fatal and the application exits after 
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Example 14-1 shows one of the rare cases where XtAppErrorMsg() is invoked in the 
Athena widgets. 

Example 14-1. How to invoke XtAppErrorMsg (from AsciiSrc.c) 
if (src->ascii_src. string == NULL) 
XtAppErrorMsg (XtWidgetToAppl icationContext (src), 
"NoFile", "asciiSourceCreate", "XawError", 
"Creating a read only disk widget and no file \ 
specified. ", NULL, 0) ; 
The error resource database is stored in a file, /usWlib/Xll/XtErrorDB, under most UNIX- 
based operating systems. The MIT distribution does not include an XtErrorDB database, but 
you can define one. Since this database is made up of one file, you must append the resource 
settings you need to this file rather than replacing it. The resource name searched for in the 
database is the concatenation of the name and type arguments specified in the calls to Xt- 
AppErrorMsg ( ) or XtAppWarningMsg ( ). 
You can redefine the routine that prints the message in order to change the fixed part of the 
message or to add features like logging of errors and warnings. Use XtAppSetError- 
MsgHandler() and XtAppSetWarningMsgHandler() (if you are using the high- 
level handlers) or XtAppSetErrorHandler ( ) and XtAppSetWarningHandler ( ) 
(if you are using the low-level handlers). See the reference pages for XtErrorMsg- 
Handler(2) and XtErrorHandler(2) in Volume Five, X Toolkit Intrinsics Reference 
Manual, for a description of how to define a new error or warning handler. The default error 
and warning messages printed are: 
X Toolkit Error: message. (for errors) 
X Toolkit Warning: message. (for warnings) 
Remember that Xt itself uses these messages (not just your widget code), so that they must 
remain appropriate when called from anywhere in the Xt, widget, or application code. If you 
want the message to identify the name of the widget set or widget, you must include this 
information in the part of the message filled in from the string you pass or from the resource 
database. 
Table 14-1 summarizes Xt's calls for issuing errors and warnings and for modifying the mes- 
sages issued. 

Table 14-1. Xt Error and Warning Message Utilities 

Message 

Issue Error 
Issue Warning 
Set Error Handler 
Set Warning Handler 

Low Level 

XtAppError() 
XtAppWarning() 
XtAppSetErrorHandle()r 
XtAppSetWarningHandler() 

High Level 

XtAppErrorMsg() 
XtAppWarningMsg() 
XtAppSetErrorMsgHandler() 
XtAppSetWarningMsgHandler() 
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Note, however, that for the high-level routines that use the error and warning resource data- 
base, there is only one database common to all application contexts, at least in the sample 
implementation of Xt provided by MIT in R4 and R5. 

When writing a high-level error or warning handler you will need to call XtGetError- 
Database() to get a pointer to the error resource database and XtGetError- 
DatabaseText ( ) to get the message for a particular set of arguments passed to XtApp- 
ErrorMsg() or XtAppWarningMsg(). For details on how to use these functions, see 
the reference pages in Volume Five, X Toolkit Intrinsics Reference Manual. 

XtDisplayStringConversionWarning() is a convenience routine to be used in 
resource type converters that convert from XmRString to any representation type. It calls 
XtAppWarningMsg() with the appropriate arguments to issue a suitable warning. Note 
however, that the class used is XtToolkitError. It may be better to use a class that 
describes the widget or widget set that defines the converter. 

14.2 Objects 

Most of this book describes how to use widgets, which are subclasses of the Core widget 
class. Chapter 13, Menus, Gadgets, and Cascaded Popups, also discusses using gadgets, 
which are subclasses of the RectObj widget class. As described there, gadgets are window- 
less widgets that are especially useful for menu panes, because they cut back on the overhead 
that would be required to implement the same thing using a widget for each pane. 
The third and final Xt class you can subclass is the Object widget class. Objects are window- 
less widgets like gadgets, but they lack geometry resources, sensitivity resources, and the 
expose method. They provide support for resources and callbacks, and that is all. 

The primary use of objects is to create replaceable sections of a widget. For example, the R4 
Athena Text widget uses objects to implement its source and sink, which control the storage 
and the display of the data respectively. By replacing the source and sink, you could develop 
a multi-color or multi-font editor without having to rewrite the central widget which imple- 
ments all the editing commands. 

An object has the following methods: class_initialize, class_part 
_initialize, set_values, and get_values_hook. All these methods have the 
same purposes as in widgets. 
While a gadget uses part of its parent's window, an object shares its parent's entire window, 
and is not managed at all by its parent since it has no geometry. The parent of an object is 
normally a widget that is a subclass of Core but not Composite or Constraint (unlike gadget 
parents). 
But like gadgets, objects depend on cooperation by their parent, and require a specially 
designed parent. The object parent's methods make calls to functions defined by the object 
child instead of doing the work themselves. The object child's functions can be either semi- 
public functions or they can be class methods defined by the object. The latter is done so that 
subclasses of the object can replace the functions. 
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As an example, let's look at how the Athena Text widget handles drawing. The drawing is 
done by the TextSink object, and its subclass AsciiSink. Although an object has no expose 
method, it provides an equivalent function that draws on the parent. This function is either a 
semi-public function (public to its parent but not to the application writer), or it is a class 
method. The Text widget uses both techniques. TextSink provides a semi-public function 
XawTextSinkDisplayText (), which is called by Text whenever drawing is needed. 
XawTextSinkDisplayText () calls one of TextSink's class methods called Display- 
Text. DisplayText is a class method so that subclasses of TextSink can replace it or inherit it. 
AsciiSink does replace this method with code that draws the text in a single constant-width 
font, in the foreground and background colors. So in order to write a Text widget that draws 
in more than two colors, you would just have to write an object that is a new subclass of Text- 
Sink. 
When Text calls XawTextSinkDisplayText (), this function calls one of TextSink's 
class methods called DisplayText. DisplayText is a class method so that subclasses of Text- 
Sink can replace it or inherit it. AsciiSink does replace this method with code that draws the 
text in a single constant-width font, in the foreground and background colors. So in order to 
write a Text widget that draws in more than two colors, you would just have to write an ob- 
ject that is a new subclass of TextSink. 
An object may assume that it should draw on its parent, but this is not necessarily the case, 
since an object could have an object as its parent. An object also has no idea of its own size, 
since it has no geometry data in its instance structure, and therefore doesn't by itself know 
what size window it is drawing into. To solve both these problems, XawTextSink- 
DisplayText ( ) passes the parent's widget ID and the parent's size into the objects draw- 
ing code. 

14.3 Macros For Getting Information 

Xt provides several macros and functions for getting information about widgets. Some of 
these, such as XtIsRealized ( ) and XtIsManaged (), you have seen before in the con- 
text of widget methods. 

Some of these are macros and some are functions, and some are macros when used in widget 
code and functions when used in application code. This does not affect how they can be 
used, so we won't bother to specify which can be both functions and macros. We will use the 
term "macro" for all of these informational routines. In Volume Five, X Toolkit lntrinsics 
Reference Manual, they are listed alphabetically, together with all of the Intrinsics functions. 

Xt provides two basic macros for determining the class of a widget: XtlsComposite ( ) 
and XtIsSubclass (). These are primarily used internally by Xt to implement geometry 
management, but you may find a use for them. For example, you might write a composite 
widget that uses XtlsComposite() to treat composite children differently than simple 
children, or uses XtlsSubclass ( ) to treat constraint children or one of your own classes 
uniquely. There are lots of convenience functions for XtlsSubclass ( ) that determine if 
a widget is a subclass of a particular class. These are XtlsObject (), XtlsRectObj (), 
XtlsWidget (), XtlsComposite (), XtlsConstraint (), XtlsShell (), 
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XtIsOverrideShell (), XtIsWMShell (), XtIsVendorShell (), Xt- 
IsTransientShell (), XtIsTopLevelShell (), and XtIsApplication- 
Shel i (). 
You have already seen XtIsManaged ( ) used in composite widgets. See Chapter 12, Ge- 
ometry Management. 
You have also already seen XtIsRealized() used in various methods to make sure a 
widget has a window before operations are attempted on the window. For example, the ex- 
pose method calls XtIsRealized ( ) before drawing into the window. 
XtIsSensitive ( ) checks the value of the XtNsensitive resource for a widget and its 
ancestors. If any of them is False, it returns False. Remember that sensitivity controls 
whether a widget responds to user events. 
XtHasCallbacks ( ) lets you tell whether a widget class has a callback of a certain re- 
source name, and whether any callback functions have actually been added to it. It returns 
the enum value XtCallbackNoList if there is no callback list, XtCallbackHasNone 
if there is a callback list with no functions on it, and XtCallbackHasSome if there is a 
callback list containing functions pointers. 
XtNameToWidget ( ) searches a hierarchy for the widget ID of the specified widget in- 
stance name. Its primary use from the application is to get the IDs of the child widgets of a 
compound widget such as Dialog, so that their resources can be set directly. This is a viola- 
tion of the rules of data hiding, however, and is not recommended. In widget code, Xt- 
NameToWidget ( ) is used to provide a layer of abstraction so that widgets can be identified 
using string names. For example, it is used by the converter defined by Form that allows 
widget names to be specified in resource files. The opposite function, which returns a widget 
instance name given the widget ID, is XtName () (which perhaps should have been called 
"'XtWidgetToName"). 
XtWindowoWidget ( ) gives you the Widget: which corresponds to the specified X win- 
dow ID. This is used mainly by Xt, but you may find a use for it. 
XtDisplayOfObject (), XtScreenOfObject (), and XtWindowOfObject () 
search the parental hierarchy of an object to discover the closest windowed ancestor and then 
return a pointer to a Display structure, a pointer to a Screen structure, or a Window ID. 
These macros are useful for making Xlib calls from within code that implements a subclass 
of Object. 
XtGetApplicationNameAndClass ( ) returns the name and class strings of an applica- 
tion. The name is usually argv [ 0 ] stripped of any directories, while the class is the string 
passed as the second argument of XtAppInitialize (). These are the name and class 
used by Xt to look up resources for the application and its widgets. You are not likely to 
need this function. 

428 

X Toolkit Intrinsics Programming Manual, Athena Edition 



14.4 The accept_focus Method and the Keyboard Focus 

The keyboard focus is the window to which the server sends keyboard events. The window 
manager controls which top-level window gets the keyboard focus (using either a click-to- 
type or pointer-following model). Once an application's top-level window gets the focus, it 
can set the focus to one of its children. 
The Core class part structure includes a field for the accept_focus method. Theoretical- 
ly, this method lets a widget set the keyboard focus to one of its children when it gets the 
keyboard focus. A typical example is an application that wants to set the keyboard focus to 
the text entry child of a dialog box whenever the dialog box is given the keyboard focus by 
the window manager. This would be done so that the user can type with the pointer any- 
where in the dialog widget instead of just with the pointer in the text entry widget. 
To implement this example, the text entry child would need an accept_focus method that 
would set the keyboard focus to itself using the Xlib call XSetInputFocus (). The dialog 
box would need an accept_focus method that called XtCallAcceptFocus ( ) on the 
text entry widget child. The application can call XtCallAcceptFocus () on the dialog 
widget in response to FocusIn events to start this process, and set the focus back to 
PointerRoot on FocusOut events. For details on these events, see Volume Two, Xlib 
Reference Manual. This procedure for giving the child of a dialog the keyboard focus is nec- 
essary because the application can't find out the name of the child that should have the focus 
without breaking widget encapsulation rules. 
In reality, none of the Athena widgets use the accept_focus method. The keyboard 
traversal code is implemented separately. 
An accept_focus method should return a Boolean value to report whether it succeeded in 
setting the keyboard focus, and XtCallAcceptFocus ( ) returns this same value. 
The XtSetKeyboardFocus() function redirects keyboard events that occur within an 
application to any widget within that application. This is different from XSetInput- 
Focus ( ) in that no request to the server is made, and the redirection of keyboard events is 
handled entirely by Xt's event dispatching mechanism. 

14.5 Keyboard Interpretation 

Keyboard handling in X is designed so that you can write a program that will operate on sys- 
tems with widely different physical keyboards. To accomplish this, there are several layers 
of mappings: 

The first mapping is between physical keys and keycodes (a number for each key), and 
varies between servers. A KeyPress event includes only the keycode and information 
about what other keys and buttons were being held at the time of the keypress. Programs 
that interpret keycodes directly will operate on only one type of system. 

The next mapping is between keycodes and keysyms, which are symbolic constants be- 
ginning with XK_ that represent the meaning of a key press. This mapping takes into 
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account whether Shift or other modifier keys were being held during the press. Xlib pro- 
vides the routine XLookupString () that converts the keycode in a key event to the 
appropriate keysym. Internationalized programs use the XmbLookupString() or 
XwcLookupStr'i ng ( ) versions which can figure out the keysym resulting from key se- 
quences entered into an input method. Portable programs use keysyms to interpret key 
events. The keycode to keysym mapping is server-wide. It can be changed, but this is 
normally done only to accomplish radical changes in the placement of keys such as 
changing a QWERTY style keyboard to DVORAK. 

The final mapping is between keysyms and strings. For printing characters, XLookup- 
String () also returns a string representation of the interpretation of the key pressed. 
For example, if the key marked A was pressed with no other keys held down, the string 
returned would be a. A text entry widget, for example, would append this string to the 
string being displayed, but modify the string in other ways to handle keysyms that do not 
have a string representation such as XK_Backspace. The values of keysyms are ar- 
ranged logically so that all printing characters have a particular range. 

When you write an action that accepts key events, you will usually need to interpret the 
meaning of the key pressed. Xt provides its own interface to XLookupString ( ) : Xt- 
TranslateKeycode(). You pass several fields of the key event to XtTranslate- 
Keycode (), and it returns the keysym. However, XtTranslateKeycode ( ) does not 
return the string interpretation of the key event that would be returned by XLookup- 
String (). If you need that string, you will have to call XLookupString (). 
Xt provides XtTranslateKeycode ( ) because X! also provides routines for changing the 
way the translation returned by XtTranslateKeycode() is done. XtSetKey- 
Translator ( ) allows you to specify your own procedure to convert from the key event 
information to a keysym. The default key event translation procedure is XtTranslate- 
Key ( ), and so you can restore the default translator if necessary, and so that you can call it 
from your own translator to get default translations (you need to add only the code that 
makes the translations not done by the default translator). See XtKeyProc in Volume 
Five, X Toolkit lntrinsics Reference Manual, for details on providing a key event translation 
procedure. 
Among these routines for modifying the interpretation of key events is a facility for changing 
the handling of capitalization. For example, most keyboards have the question mark (?) sym- 
bol over the slash (/) symbol on one key. The standard case converter converts a press of this 
key with the Shift key held down to the XK_question keysym. In rare cases a keyboard 
may have a different symbol over / and put ? somewhere else. Also, some keyboards have 
two or more symbols on a single key, some of which are not represented at all by standard 
keysyms. The case converter handles these situations. The case converter is usually called 
from the key translator described above. To call the case converter, use XtConvert- 
Case(), and to change the case converter, call XtRegisterCaseConverter (). See 
XtCaseProc in Volume Five, X Toolkit lntrinsics Reference Manual, for details on writing 
a case converter procedure. 
Note that the translation manager uses these same key translation and case converter routines 
to interpret translation tables. Therefore, make sure that you add features only to them, keep- 
ing existing features. 
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Xt also provides two routines that may help in interpreting key events: XtGetKeysym- 
Table ( ) and XtKeysymToKeycodeList (). The former returns the entire mapping of 
keycodes to keysyms for the server, while the latter tells you what keycodes are listed for the 
specified keysym. Neither function is necessary for routine keyboard handling. 

From within an action routine, you can call XtGetActionKeysym() to get the keysym 
that resulted in the action being called. This can be very useful, since the event passed to the 
action contains only the keycode of the key that was pressed. However, there is another way 
to achieve a similar result. You can use string parameters of actions to pass in the keysym 
that you specified in the translation table. For example, if you provide the translation 
:<Key>q : Quit (q), the Quit action will be passed the string "q" in its loarams argu- 
ment. However, XtGetActionKeysym ( ) is very useful if you translate a wide range of 
key events to one action, and then want to distinguish between them in the action. 

14.6 

Memory Allocation 

Xt provides routines for performing routine memory allocation and deallocation. The rou- 
tines XtMalloc (), XtCalloc ( ), XtRealloc ( ), and XtFree ( ) are equivalents of the 
standard C routines malloc, calloc, realloc, and free but they add error checking 
and reporting. The allocation routines make sure the allocation succeeded, and if it did not, 
they print a (fatal) error message. XtFree ( ) makes sure the passed pointer is not NULL be- 
fore calling free. 
XtNew ( ) is a macro which allocates storage for one instance of the passed type and returns 
a pointer. For example, XtNew (XtCallbackList) allocates storage for one callback list 
structure. XtNewString ( ) is a macro that allocates storage for a string, copies the string 
into the new storage, and returns the pointer. For example, a string can be copied into new 
storage using the following: 
static String buf [ ] = "How do you do? "; 
String p; 
p = XtNewString(buf) ; 
After this sequence, p points to a separate string that contains "How do you do?" Then buf 
can be changed without affecting p. 

14.7 Action Hooks and Calling Actions Directly 

Xt allows you to register any number of functions to be called whenever any action in an ap- 
plication context is invoked. This is done with XtAppAddActionHook(). Note that 
there is just one "'action hook" in the application context, so that all the action hook functions 
registered for that application context are called whenever any of the actions in that applica- 
tion context are invoked. The registration does not specify any particular action or any par- 
ticular widget. 
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The main reason for registering an action hook is to record all the actions that were invoked 
in an application, so that they can be played back later using XtCallActionProc (). An 
action hook function is called with all the same arguments that are passed to an action, plus 
the string name of the action. The action hook function would store this information as a unit 
each time it was called. When it comes time to play back the recorded actions, it would pass 
all the information in each unit to XtCallActionProc ( ). 

An action hook can be removed with XtRemoveActionHook (). 

14.8 Xt Grabbing Functions 

Grabs are used mostly for pop-up menus and dialog boxes. As described in 
Chapter 13, Menus, Gadgets, and Cascaded Popups, Xt has its own grab mode that controls 
the distribution of events within one application, which can be used to restrict events to one 
popup in a cascade or allow events to go to any popup in a cascade. As also described there, 
pop-up menus in particular need a passive global grab of the pointer in order to detect button 
releases that occur completely outside the application so that menus can be popped down 
properly. A passive global grab actually instructs the server to redirect events to a certain 
window. All the grabbing needs of popups are satisfied by the built-in action XtMenu- 
Popup ( ), or by the function XtPopupSpringLoaded (), which can be used in a call- 
back function. If necessary, you can write your own version of XtMenuPopup ( ) and regis- 
ter it with XtRegisterGrabAction ( ) so that the appropriate passive global grab is in 
effect. 

The above facilities should be quite sufficient for your needs in the area of popups. However, 
it is possible that you may need an global grab for some other purpose. Perhaps you need all 
keyboard events in one window for a short time and don't want to change existing transla- 
tions or accelerators for keyboard events in other widgets. This is only one plausible sce- 
nario. 

The Xlib functions for grabbing are XGrabKey(), XGrabButton(), XGrab- 
Keyboard(), and XGrabPointer(). Each of these functions has an analogue for 
ungrabbing. But Xt provides its own version of all eight of these functions. You should use 
the Xt versions because they are integrated into Xt and take care of things like making sure 
the widget that is to get the grab has been realized. In other words, if you do need the server 
to redirect events for you using a grab, use the following functions: XtGrabKey(), Xt- 
GrabButton ( ), XtGrabKeyboard (), XtUngrabKeyboard (), and XtUngrab- 
Pointer (). For more on global grabs, see Chapter 8 in Volume One, Xlib Programming 
Manual. 
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14.9 File Finding and Internationalization 

Xt's facilities for allowing an application to run in different languages are mostly built into 
the resource database mechanism. Where Xt searches for resource files depends on a lan- 
guage string, which can be set within resources at run time or with an environment variable 
to affect one user's environment. This is described in Chapter 10, Resource Management 
and Type Conversion. In R5 and later, Xt also uses the value of the XtNcustomization 
resource to set the path it uses when looking for application defaults and other files. 
XtNcustomization is normally used to supply separate sets of resources for color and 
monochrome screens. 
The functions that Xt uses to implement its search for resource files are also available to you 
for searching for application files. This allows you to provide separate data files for each lan- 
guage for a help system, for example. The primary function you would use to do this is Xt- 
ResolvePathna_me (), since it searches directories in a standard order based on X/Open 
Portability Guide conventions. 
If you want to find a file but are not interested in internationalization, you can use XtFind- 
File (). This function can simplify code that reads files, since it helps handle differences in 
file systems. 

14.10 Application Contexts 

The introduction to application contexts in Section 3.9 described their use in 99 percent of 
applications. As you may recall, their purpose is chiefly to attain portability to certain sys- 
tems that do not provide a separate address space for each process. 

Xt provides parallel versions of many routines--one set that uses the default application con- 
text, and one set that has an explicit application context argument. The routines that use the 
default application context are remnants of an earlier release when application contexts did 
not work properly. To achieve the desired portability, you must now use the versions with the 
explicit argument. We have done this throughout this book. In Volume Five, X Toolkit ln- 
trinsics Reference Manual, the reference pages for all the functions that use the default appli- 
cation context note the fact that they should no longer be used. 

Table 14-2 shows the complete list of routines that have two versions. 

Table 14-2. Xt Routines That Use Default and Explicit Application Contexts 

Default 

(registering functions) 
XtAddActions ( ) 
XtAddConverter ( ) 
XtAddInput ( ) 
XtTime0ut ( ) 

Explicit 

XtAppAddActions() 
XtAppAddConverter() 
XtAppAddlnput() 
XtAppTime0ut() 
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Table 14-2. Xt Routines That Use Default and Explicit Application Contexts (continued) 

Default 

XtWorkProc ( ) 
(creating shells) 
XtCreateApplicationShell ( ) 
(event dispatching) 
XtMainLoop ( ) 
XtNextEvent ( ) 
XtPeekEvent ( ) 
XtPending ( ) 
XtProcessEvent ( ) 
(error and warning messages) 
XtError ( ) 
XtErrorMsg ( ) 
XtGetErrorDatabase ( ) 
XtGetErrorDatabaseText ( ) 
XtSetErrorHandler ( ) 
XtSetErrorMsgHandler ( ) 
XtSetWarningHandler ( ) 
XtSetWarningMsgHandler ( ) 
XtWarning ( ) 
XtWarningMsg ( ) 
(selection timeouts) 
XtGetSelectionTimeout ( ) 
XtSetSelectionTimeout ( ) 
(action hooks) 
(no equiv) 
(toolkit initialization) 
(no equiv) 
(resources) 
(no equiv) 
XtSetTypeConverter ( ) 
(no equiv) 

Explicit 

XtAppWorkProc ( ) 

XtAppCreateShell() 

XtAppMainLoop ( ) 
XtAppNextEvent ( ) 
XtAppPeekEvent ( ) 
XtAppPending ( ) 
XtAppProcessEvent ( ) 

XtAppError() 
XtAppErrorMsg() 
XtAppGetErrorDatabase() 
XtAppGetErrorDatabaseText() 
XtAppSetErrorHandler() 
XtAppSetErrorMsgHandler() 
XtAppSetWarningHandler() 
XtAppSetWarningMsgHandler() 
XtAppWarning() 
XtAppWarningMsg() 

XtAppGetSelectionTimeout() 
XtAppSetSelectionTimeout() 

XtAppAddActionHook() 

XtAppInitialize() 

XtAppSetFallbackResources() 
XtAppSetTypeConverter() 
XtAppReleaseCacheRefs() 

Note that XtCreateApplicationShell ( ) and XtAppCreateShell ( ) have names 
that don't follow the example set by all the rest. 

14.10.1 

Multiple Application Contexts 

The use of more than one application context in a single program presents possibilities that 
you might wish to explore. Having more than one application context in the same program 
allows you to have one program that when run looks like two or more independent programs. 
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This approach saves disk space and memory on systems that don't provide shared libraries, 
since the grouped programs can share a single copy of the libraries.'t" 

Having two application contexts makes each sub-application more separate than if they were 
just under different top-level Shell widgets. Each widget class has an action list, and each 
application context has a separate context-wide action list. When the translation manager 
looks for an action, it looks in the widget class action list first, and then the application con- 
text action list. Therefore, each sub-application could add an action to its application context 
without conflict with another sub-application adding a different action of the same name. 

On parallel processing machines, each separate application context could run in parallel. 
However, it is difficult to write portable code to take advantage of this, since each architec- 
ture has different conventions for indicating parallelisms in C code. 

14.10.2 

Rewriting XtAppMainLoop for Multiple Application Contexts 

To use multiple application contexts, you need to write your own equivalent of XtApp- 
MainLoop ( ) to dispatch events to your multiple application contexts. This is necessary be- 
cause XtAppMai nLoop ( ) dispatches events only from one application context, and it nev- 
er returns so you can't call it again for the other. 
The available tools are XtAppNextEvent ( ), XtAppPeekEvent ( ), XtApp- 
Pending(), XtAppProcessEvent(), and the Xlib functions XFlush() and 
XSync (). Rewriting XtAppMainLoop ( ) for two or more application contexts is tricky, 
because you don't want to let the dispatching of any one application context get behind. It is 
not as simple as dispatching events from each application context alternately, since the 
events might not occur alternately. It is easy to get stuck waiting for events in one applica- 
tion context while events queue up at the other. There is little experience in how this should 
be done properly, and no examples in the distribution from MIT. However. hypothetically, 
the following describes how it could work. 
To do this properly, you have to understand how Xlib's network optimization works. Xlib 
buffers up many types of requests and sends (flushes) them to the server as a group.$ A flush 
is most commonly caused by a routine such as XtAppNextEvent ( ) that waits for an event 
if none are available. It is because XtAppNextEvent ( ) waits forever for an event that the 
routine could get locked waiting for events in one application context while the user types 
frantically in the other. 
The answer is to use XtAppPending() to determine whether an event is available on a 
particular application context, and then call XtAppProcessEvent ( ) if there is an event 
to process. Then continue to do the same on each other application context. However, this 
"t" In SunView, many of the basic applications were grouped in a single binary probably for this reason. The Xlib and 
Xt libraries are quite large. For example, on a Sony NWS-841 workstation, the executable image of a "hello, world" 
application written with Xt and the Athena widget set uses 450K of disk space. One of the most complicated existing 
X applications, xterm, uses 600K of disk space on this system. Therefore, the various libraries account for about 
three-quarters of the disk space used, even for a fairly large program. 
:l:For a detailed discussion of Xlib's network optimization and its effects, see the introduction to Volume Zero, X 
Protocol Reference Manual. 
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alone is not enough. Neither XtAppPending ( ) nor XtAppProcessEvent ( ) called in 
this manner cause Xlib's buffer of requests to be sent to the server. Therefore, periodic calls 
to XSync ( ) or XFlush ( ) are necessary to flush the output buffer. The difficult part is to 
call these enough to flush the buffer when necessary, but not so much as to eliminate the ad- 
vantages of the buffering. There is no ideal solution to this problem. 

On multi-tasking systems it is perhaps possible to fork so that each application context runs 
in a separate process. 

14.10.3 

Functions Used with Multiple Application Contexts 

The functions XtWidgetToApplicationContext ( ) and XtDisplay- 
ToApplicationContext ( ) could be useful if you use more than one application con- 
text in an application. XtWidgetToApplicationContext () is also useful in widget 
code, to call error-issuing routines that require an application context argument, such as Xt- 
AppWarning ( ) and XtAppWarningMsg (). 

14.11 

Multiple Top-level Shells 

A single application can have more than one top-level window. In other words, you are not 
restricted to containing your application's entire user interface in a single rectangle. If you 
have one section of the application that is most appropriate as a long, thin vertical window 
that looks like a long, permanent menu, and another section that is a long, horizontal bar such 
as a ruler, each of these could be a separate top-level window. That way, not only is less 
screen space wasted than if these two windows were placed within a single rectangle, but the 
user can move the two windows around separately using the window manager. The user can 
also iconify them separately when not needed. 
To create additional top-level application shell widgets, you call XtAppCreateShell () 
or XtVaAppCreateShell (). (XtCreateApplicationShell ( ) is now superced- 
ed.) The class specified in the call should be topLevelShellWidgetClass. 
As you may know, a single server may have several screens attached. At present, all shells 
created will appear on the default screen. There is no way for the application to specify that 
a shell be created on a particular screen, but then again, doing this is usually unwise anyway 
because not many users actually have more than one screen. The user can specify which 
screen is considered the default screen using the -display command-line option. 
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A class extension structure is defined in the private header file of a widget class. The exten- 
sion structure for Composite is called CompositeClassExtensionRec as shown in Ex- 
ample 14-2. 

Example 14-2. Common fields in a class extension record 
typedef struct { 
XtPointer next_extension;/* ist 4 mandated for all ext rec */ 
XrmQuark record_type; /* NULLQUARK; on CompositeClassPart */ 
long version; /* must be XtCompositeExtensionVersion */ 
Cardinal record_size; /* sizeof(CompositeClassExtensionRec) */ 
Boolean accepts_obj ects; 
} CompositeClassExtensionRec, *CompositeClassExtension; 
All extension structures start with the same four fields. The only field in this structure actu- 
ally used by Composite is accepts_objects, the use of which is described in Section 
12.4.5. The accepts_objects field is only used by Composite widgets that have the 
code necessary to accept gadget children. When a widget class needs an extension feature, 
the widget class initializes the extension structure in its .c file, and then in the class_ 
initialize method sets the extension field to point to the extension structure. 
When a widget class does not need an extension feature--for example, a Composite widget 
that does not accept gadget children--the widget class does not provide code in the 
class_initialize method to set the extension field. 
The .c file of all widget classes should initially set all extension fields to NULL. The dif- 
ference between classes that use extension features and those that don't is only the presence 
or absence of code in class_initiali ze to set the extension fields. 
The four required fields in an extension structure are: 
next_extension Specifies the next record in the list, or NULL. 
record_type Specifies the particular structure declaration to which each extension 
record instance conforms. 
version Specifies a symbolic constant supplied by the definer of the structure. 
record_si z e Specifies the total number of bytes allocated for the extension record. 
When you initialize an extension structure of a given class in the .c file, you always set these 
four fields to the same values. Example 14-3 shows how to initialize the Composite exten- 
sion structure. The first two fields are usually NULL and NULLQUARK. The reference page for 
each class that has an extension structure will document how to initialize the third and fourth 
fields. 
CompositeClassExtensionRec extension_rec = { 
/* next_extension */ NULL, 
/* record_type * / NULLQUARK, 
/* version */ XtCompositeExtensionVersion, 
/* record_size */ sizeof(CompositeClassExtensionRec), 
/* accepts_objects */ True, /* only n field */ 
); 
The next_extension field implies correctly that you can nest extension structures. Per- 
haps a later release of Xt will require the addition of more Composite class fields. These 
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could be added to the end of the existing extension structure, or a new extension structure 
could be defined and a pointer to it placed in next:_ext:ension. This allows additions to 
be made to a class structure without breaking binary compatibility. 

You may be wondering whether you should use extension structures when extending your 
own widgets. Probably not. Because you are likely to release your set of widgets as a pack- 
age, you have no need for binary compatibility with previous releases (of your own). Binary 
compatibility would only be an advantage if you wanted to replace a few widgets from a for- 
mer release and save users who may have subclassed the widgets you have replaced from 
recompiling their widgets. For the trouble involved, the benefit is very small. 

14.14 Using Editres in Xt Programming 

editres is a tool for viewing the structure of X Toolkit applications, finding and setting re- 
sources, and dynamically see the results of such settings, editres can help programmers cre- 
ate an app-default file and fallback resources and test custom Xt widgets. This section de- 
scribes how to use editres as an aid in debugging widgets and applications.: 

4.14.1 A Tour of editres 

The editres application is part of the core distribution in Release 5. This section is a brief 
tour of the editres resource editor. It will illustrate how to use editres to customize an X 
Toolkit application. When the user starts editres it looks like Figure 14-1. 
The editres application contains four areas; The Menu Bar, the Panner, the Message Area, 
and the Tree Display (which is initially empty). You begin by choosing Get Widget Tree 
from the Command menu and, following the instructions in the Message Area, select an X 
Toolkit application by clicking a pointer button. Figure 14-2 shows the result of selecting the 
xman application. (Note that the application must have support for editres. All applications 
written using the Athena widget set have that support built in as of R5. 

1"This section was written by Chris D. Peterson of Integrated Computer Solutions A version of it originally appeared 
in The X Resource, Issue O. 
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The Tree Display now contains the widget hierarchy ofxman, displayed graphically. You can 
now see the name of each widget in the application, and the parent-child relationship of each 
of these widgets. By using the Tree menu or a keyboard accelerator the user can also see the 
Class names, Widget ID's, or Window ID's. Figure 14-3 shows the same xman application, 
but with the Window ID's displayed instead of the widget names. 

wn: Ox80002b 

wn: 0x800035 

wn: 0x80002c 

wn: Ox80002d 

wn: 0x800038 

Figure 14-3. editres display window IDs of widget tree 

By selecting "Select Widget in Client" from the Tree menu you can click a pointer button 
anywhere in the application, and editres will highlight the corresponding widget in the Tree 
Display. Figure 14-4 shows the result of clicking in the topLabel widget of the xman applica- 
tion. Editres can also do the inverse of this; selecting the "Flash Active Widgets" command 
from the Tree menu will show you (by flashing widgets in the application) which widgets are 
currently selected in the Tree Display. 

With these two commands you can easily determine the correspondence between the applica- 
tion itself and the Tree Display representation of it. Because a resource specification is sim- 
ply a description of the widget's locations in the Tree Display and can be constructed by con- 
catenating the names of the widget and it ancestors, editres can easily construct valid re- 
source specifications that apply to the widgets selected. For example, the fully specified re- 
source name of the topLevel widget is xman.topBox.form.topLabel. 

Miscellaneous Toolkit Programming Techniques 441 



._ 
 Wldget Tree or cllent xlan(Xlan). 
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 Hanua Page 

Figure 14-4. Flashing widget in application by selecting it in editres 

Once you find the widget you want to modify you can select the Show Resource Box com- 
mand to bring up a dialog box that will allow you to set the resource of that widget. A Re- 
source Box is shown in Figure 14-5, as it would look after changing the topLabel widget's re- 
source to "Testing, Testing." 

At the top of the Resource Box is the resource line currently being edited. This is the actual 
string that will be inserted into the resource file if you decide to save a change. Below this is 
an area that allows you to modify the widgets to be affected by this change. This area allows 
you to substitute class names for instance names, and asterisks for periods in the left hand 
side of the resource specification. These changes will loosen the binding of the resource 
specification allowing this one resource line to apply to more and more widgets (see Figure 
14-6). Note that no matter how the bindings are modified (by changing periods to asterisks) 
the original widget will always match the specification. 

When taken to the extreme, the resource specification can apply to every widget in the appli- 
cation. As you change the bindings of the resource specification, the Tree Display is updated 
to highlight all the widgets that will be affected by the resource line displayed. When this is 
combined with the Show Highlighted Widgets command, which flashes the widgets in the ap- 
plication that correspond to those highlighted in the Tree Display, you can quickly determine 
which widgets will match a given resource specification. 
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The next area contains a complete list of normal and constraint resources that are available 
for the originally selected widget. This area is used to select the name of the resource that 
the user wishes to modify. Foreground, for example, will set the foreground color. Below 
this area is simply a text field to allow the user to enter the string that will represent the re- 
source value. The resource value that is entered here should be exactly what would be en- 
tered into a resource file, thus all new lines should be escaped by a backslash (\) and 
backslash-n (\n) should be used to add a new line to the resource value. 

NOTE 

Since editres specifies all resources as strings, it can only set those resources that 
can be set from resource files. Athena along with Xmu provides converters 
(from String) for all its resources, but some widget sets do not. 

The commands at the bottom of the Resource Box allows the user to select the file the re- 
sources will be written into, write the resources to the file, apply the resource immediately to 
the application, or just pop down the resource box. 
Note that applying the resource to the application will not always have the same effect as res- 
tarting the application with the resource added to the user's customization file. This is a de- 
sign constraint of the X Toolkit. Some resources are designed to be read once at startup, and 
trying to coerce them into a dynamic resource editor is problematic. The basic problem is 
that the editres support in the application uses XtSetValues ( ) to change the resource of 
the selected widgets. An XtSetValues ( ) call after startup will override any hard-coded 
application defaults (but not application defaults specified in files or as fallback resources), 
whereas the same resource specification in a resource file will not. Therefore, the results of 
applying a resource setting using editres are only a guide. 
Those are the basic features of editres. You can see there is much work to be done, but the 
basic task of finding and setting resource values is much simpler with this tool. This brief 
tour should give you an idea of the capabilities of the resource editor, and hopefully stir your 
imagination a bit. I will next describe the method editres uses to communicate with the ap- 
plications. 

14.14.2 editres as a Programmer's Tool 

The programmer can use editres to help understand the structure of the application or devel- 
op resource settings to be used as the app-defaults file or fallback resources. 
The editres tool can also be useful for testing newly written or modified widgets. The test 
program can be written generically and then editres lets you see the results of various re- 
source settings. The tests allow the widget's geometry_manager and set_values 
methods to be debugged more quickly and with much less effort than is possible without edi- 
tres. 
Before you can do debugging or testing with editres, you need to find out if the application 
you will be using has editres support, and if not, add it. 
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14.14.3 Using editres to Understand the Structure of an Application 

Picking up maintenance of an X application that was written by someone else can be an exer- 
cise in patience. Because of the event driven nature of X applications there is no single flow 
of control. In order to find out what is happening it is often necessary to locate the place 
where a widget on the screen is created in the code and then use this information to find its 
widget ID and display the data contained in that widget, editres can make this task much 
simpler. 

To find the place where a widget is created, use the "Select widget in client" command, and 
click the pointer on the widget of interest within the target application. This will highlight 
that widget in editres's tree display. The tree display will show the name of the widget, 
which makes finding where it was created easier, usually a simple matter of using grep(1). 
You can also view the widget's class name, widget ID and window ID by selecting various 
commands from the Tree menu, or using the keyboard accelerators described below. 

Table 14-3. editres accelerators 

Accelerator 

N 
C 
I 
W 

Description 

Show widget name 
Show widget class 
Show widget ID (in hex) 
Show widget's window 

If the pointer is over a widget when the accelerator is used then only that one widget is af- 
fected. If the pointer is over the tree background then all widgets in the application are af- 
fected. 
When viewing the widget windows, the programmer is also informed if the widget is unreal- 
ized or if the widget in question is a non-windowed object, such as an Object or a Motif Gad- 
get. This information is often useful when attempting to decipher an X protocol error, since 
it contains the XID of the offending widget. The class names can be useful to help under- 
stand the behavior, and geometry constraints of the current application's window layout. 
Widget ID's are mainly useful when used in concert with a symbolic debugger such as dbx or 
CodeCenter (formerly Saber-C), since the values in the widget structure can be viewed in the 
debugger by de-referencing this widget pointer. 
To provide a permanent hard copy of the widget hierarchy of an application, either for future 
reference, or for inclusion in the application's documentation, editres provides a command 
called "Dump Widget Tree to a File." The output is dumped in an outline format and in- 
cludes both the name and class of each widget currently in the application. Note that this 
command will only show those widgets that had been created the last time a "'Get Widget 
Tree", or "Refresh Current Widget Tree" command was executed. 
In addition to allowing the programmer to understand the structure of an application, editres 
can be used to add entries to an application defaults resource file. To use editres as an aid 
simply use the "Set Save File" button at the bottom of the Resource Box, and then use the 
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"Save and Apply" button to add entries to the application defaults file. editres immediately 
applies the resource change to the application. 

14.14.4 

14.14.4.1 

Using editres to Test or Debug a Widget 

The programmer can also use editres to test some of the dynamic characteristics of a widget. 
Since a widget's most common interface to the outside world is through the setting of re- 
sources, the "Apply" action in editres's resource box window provides a very convenient 
mechanism for testing and debugging widget resources. This mechanism can be used to test 
the widget's set_values and Constraint set_values procedures, as well as the widg- 
et's geometry_manager. 
editres gets its list of resources for a widget by sending a message to the application. The 
editres support code in the application that receives the message then calls the Xt functions 
XtGetResourceList ( ) and XtGetConstraintResourceList ( ) to get the list of 
resources supported. Xt does not provide functions for getting the list of resources for appli- 
cation resources, objects that are not Xt children or Xt pop-up children, and subresources, so 
they are not visible to editres. This limitation appears in most Text widgets, because they use 
either objects or subparts that have subresources, and editres cannot find these resources. 
Editres passes only string values across to the application to set resources. Therefore, the 
editres support code in the application uses a StringTo<something> converter to actually set 
the widget resource. If no such converter is available, editres will not be able to set the re- 
source. Since these converters are required to allow the resource to be set in the app-defaults 
file or user resource file, your widget should have them anyway, so you should not need to 
add any special code to your widget in order to debug it using editres. 

Testing a Widget's set_values Procedures 

To test a widget's set_values procedure you must first pop up the resource box associated 
with that widget. The resource box is popped up by selecting the widget in question and se- 
lecting the "Show Resource Box" command. This will pop up a window that shows all the 
resources available to this widget. Selecting a resource, entering a value, and hitting the Ap- 
ply button at the bottom of the Resource Box window allows the programmer to test each re- 
source of this widget to verify that it is responding to them correctly. 

Note that each widget must register a type converter from String to each new type of resource 
it created, since editres sends all values as strings. Writing and registering these converters is 
a good idea in any case, since it allows each widget resource to be specified in the app-de- 
faults file or another resource file as well as through the set_values mechanism. 

It is important to note that changes to a resource defined by the superclass may often require 
support from the subclass. If your new widget, which is a subclass of an existing widget, has 
added some additional functionality to a resource that is not new to this widget, but was de- 
fined by its superclass, you must test this resources as well (e.g., a Label widget will need to 
test the sensitivity resource, since it added support for stippling the text when it becomes in- 
sensitive). Programmers should be sure to modify the value of each resource, not just those 
new resources added to this widget. 
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14.14.4.2 

To test the Constraint set_values procedure of a widget the Resource Box of a child of 
this widget must be popped up. This Resource Box window will list the constraint resources 
separately from the normal resources. These resources can be tested with the apply button in 
the same fashion as normal resources. 

Testing a Widget's geometry_manager 

Although it is not obvious at first, editres can be used to test a widget's geometry manager. 
Since the size and location of every widget are stored in resources they can be modified on- 
the-fly with editres. 
First identify the widget whose geometry manager is to be tested. I will call this widget the 
"parent." To test its geometry manager we must make a request to change the geometry of 
one of its children. Therefore, use editres to select one of the children of the "parent" widget 
and pop up its Resource Box. This will allow the child's size and location to be changed by 
modifying the x, y, width, and height resources. Changing these attributes will in turn call 
upon the geometry manager of the parent widget, allowing the programmer to see if the prop- 
er behavior is occurring. By placing several different kinds of children in the parent and see- 
ing how changes to the geometry of each child affects the others, extensive testing can be 
performed in a short period of time. 
Since two resources cannot be modified in a single editres command there is no direct way to 
make a simultaneous width and height change to a widget. But if a Xaw Label or XmLabel 
widget is used as a child then a change to the font will often cause a change to both the width 
and height of the widget. The effects of such a change can then be tested in the parent's ge- 
ometry manager. 
editres may be expanded to include additional features. 

14.15 Internationalization in the X Toolkit 

In X 11R5, Xt was modified to better support internationalization. An internationalized appli- 
cation reads the user's language (called a locale) from the environment or a resource file and 
operates in that language without changes to its binary. X internationalization is based on the 
ANSI-C internationalization model. The concepts and implementation of X internationaliza- 
tion are described in the Third Edition of Volume One, Xlib Programming Manual. Xt sup- 
port of internationalization is trivial in most applications: the only code needed is a call to 
XtSetLanguageProc () just before the call to XtAppInitialize (). However, if 
your program directly manipulates text from widgets, or you need to write widgets that ac- 
cept text input or draws text, you'll need to understand Xlib's internationalization features. 
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A 

Athena, OPEN LOOK, and Motif 

This appendix gives an overview of the widgets available in Sun's OPEN 
LOOK widget set (known as OLIT, the OPEN LOOK Intrinsics Toolkit), the 
OSF/Motif widget set, and the Athena widget set. It gives a sense of the look 
and feel of applications developed with each set, and provides the inheri- 
tance hierarchy and overview of the available widgets. 
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A 
Athena, OPEN LOOK, and Motif 

This section provides an overview and comparison of the widgets in MIT's Athena widget 
set, Sun's OPEN LOOK widget set (known as OLIT), and the Open Software Foundation's 
Motif. 
As we've already discussed, the Athena widgets were developed to test and demonstrate the 
Xt Intrinsics. They are used as the basis for some of the standard MIT clients and many pub- 
lic domain applications, but are not expected to be used for most commercial applications 
because Xaw is not a complete environment. However, it is freely available. 
A number of vendors have developed proprietary widget sets. Given that one of the purposes 
of widgets is to provide a common look and feel for X applications, it is natural there should 
be a shakeout as vendors align themselves with one or two major contenders. As it has 
turned out, the two major contenders for a graphical user-interface standard, OPEN LOOK and 
Motif, are put forth by the two major contenders for an underlying UNIX operating system 
standard, AT&T and the Open Software Foundation. 
It is theoretically possible to write an application that will run under either of these widget 
sets, using one set of source code interspersed with #5.frier symbols for conditional compi- 
lation. This becomes more difficult when you use any of the Xt-level features that Motif 
alone provides, however. 
OPEN LOOK is somewhat unusual in that it started out not as a set of widgets, but as a user- 
interface specification. The specification, originally developed by Sun Microsystems with 
AT&T backing, was widely circulated for comment before any implementations were begun. 
The objective was to develop a graphical user-interface standard for UNIX worksta- 
tions-one that would be implementation-independent, and, it was hoped, implemented sep- 
arately by many different vendors. 
At present, the two major implementations of OPEN LOOK are Sun's XView toolkit (which is 
not based on Xt, but instead provides an application-programmer's interface similar to Sun's 
proprietary SunView windowing system), and AT&T's OPEN LOOK Xt-based widget set 
(known as OLIT). XView is on the R5 distribution from MIT. Both of these toolkits are 
available to AT&T UNIX System V Release 4 licensees. In our discussions, we are referring 
specifically to AT&T's OPEN LOOK toolkit, which does not necessarily include every OPEN 
LOOK feature. Nor should its implementation be considered the only way to provide features 
called for by OPEN LOOK. 
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The Open Software Foundation's Motif toolkit is based on a combination of widget sets orig- 
inally developed by two OSF sponsors, Digital and Hewlett Packard. The look and feel of 
the widget set was proposed by HP/Microsoft. It is designed to emulate the look and feel of 
the IBM/Microsoft Presentation Manager standard widely expected to be adopted in the 
microcomputer world. Motif l.i is fully compatible with the MIT Release 4 Intrinsics. 
Motif 1.2 is fully compatible with the MIT Release 5 Intrinsics. Motif 1.2, released in May 
1992, is described here. 

Table A- l compares the widgets available in Athena, AT&T OPEN LOOK set, and Motif. 

Table A-1. Comparison of Athena, OPEN LOOK, and Motif Widgets 

Simple widgets (mostly controls): 
Athena OPEN LOOK 

Command 
-- 
Toggle 
-- 

MenuButton 

Scrollbar 

Grip 
Label 
Text 
-- 

OblongButton 
-- 
RectButton 
CheckBoxt 

ButtonStack 

AbbrevStack 

ScrollingList* 

Motif 

PushButton 
DrawnButton 
ToggleButton 
CheckBox, RadioBox 
CascadeButton 
OptionMenu 
ArrowButton 
List 

Scrollbar 
Slider 

StaticText 
Text 
TextField 

ScrollBar 
Scale* 

Label 
Text 
TextField 

Separator 

*CheckBox, ScrollingList, and Scale are technically composite widgets. 

Description 

Invokes a command 
Invokes a command 
Chooses a setting 
Alternate way of 
choosing a setting 
Invokes a menu, dis- 
plays label 
Invokes a menu, dis- 
plays default 
Reverses direction of 
movement 
Displays a list of select- 
able strings 
Scrolls through an 
associated window 
Sets (or displays) an 
analog value 
Resize point for panes 
in VPaned 
Displays a fixed string 
Displays editable text 
Displays a single line 
of editable text 
Displays a line or other 
separator 
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Table A-1. Comparison of Athena, OPEN LOOK, and Motif Widget (continued) 

Popups (subclasses 

Athena 

SimpleMenu 
-- 

r shell): 
OPEN LOOK 

Menu 
Notice 

PopupWindow 

Help 

Motif 

MenuShell 
DialogShell 
MessageBox 
MessageBox 

Description 

Parents a pop-up menu 
Displays a dialog 
requiring input 
Displays a more com- 
plex dialog 
Displays a help win- 
dow 

Composite and Constraint Widgets: 
Athena OPEN LOOK 

Box 

FOnTl 

Viewport 

VPaned 

BulletinBoard 

ControlArea 

FOnTl 

Exclusives 

Nonexclusives 
FooterPanel 

ScrollingListl" 

Caption 
ScrollingWindow 

Motif 

BulletinBoard 

DrawingArea 
-- 

RowColumn 

RadioBox 

CheckBox 

Frame 
SelectionBox 

Command 

FileSelectionBox 

ScrolledWindow 
MainWindow 
PanedWindow 

Description 

Free-form placement 
area 
Free-form drawing area 
Displays children in 
order added 
Arranges children in 
rows or columns 
Manages children rela- 
tive to each other 
Makes RectButton chil- 
dren exclusive 
Makes RectButton chil- 
dren nonexclusive 
Provides a consistently- 
sized message area 
Gives consistent border 
to enclosed widgets 
Provides a selectable 
list of strings, plus a 
text area for entering a 
new value 
Provides a selectable 
list of commands 
Provides a selectable 
list of filenames 
Displays a label and 
one child widget 
Displays a scrollable 
child window 
ScrolledWindow with 
special appearance 
Displays panes resiz- 
able in one direction 

"l'Checkbox, ScrollingList, and Scale are technically composite widgets. 
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In addition to base windows, applications may have several kinds of popup. Both pulldown 
and pure pop-up menus are supported, as well as several standard kinds of notices and dia- 
logs. Probably OPEN LOOK's best-known feature is the "pushpin" metaphor that allows fre- 
quently-accessed pop-up menus to be kept on the screen rather than hidden again after hey 
have been used. A similar feature was added to Motif in version 1.2. 
The following sections discuss some of the widgets AT&T has provided to support the OPEN 
LOOK user interface. Figure A-2 shows the overall widget inheritance hierarchy. 
Note that there are a number of widgets that are never instantiated by the application pro- 
grammer, but are used by other widgets. For example, the checkbox is actually a composite 
widget that manages a check widget as its child! The Pushpin used in popups and the Magni- 
fier used in Help windows (and the Help window itself) are examples of other widgets that 
are not instantiated directly. 

A.1.1 

A.1.1.1 

Application Controls 

Most applications will have at least one control area, with pointer-selectable buttons that 
invoke commands or menus, or choose settings. 

One of the areas where OPEN LOOK clearly stands out over the Athena widgets is in the rich 
set of controls it provides. Athena has one kind of Command widget; OPEN LOOK has six. 

Command Buttons 

The Athena Command widget implements one of the most basic user-interface idioms--a 
button that invokes an action when you click on it with the pointer. The Athena widgets 
include a subclass of Command, the MenuButton widget, which includes code for placing a 
pop-up menu. 

The OPEN LOOK widget set implements similar functions using the OblongButton and 
ButtonStack widgets. Figure A-2 shows a Control Area containing OblongButton and 
ButtonStack widgets. Figure A-3 shows the class inheritance hierarchy of the AT&T OPEN 
LOOK widgets. 

I CRectang le 

Figure A-2. An OPEN LOOK ControlArea with OblongButton and ButtonStack widgets 
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A.1.1.2 

double line, to give the user immediate visual feedback about which button to choose when 
several are available. 

The OblongButton also has the notion of a "busy" state in which it cannot perform the action 
because it is already doing it. (This is different from a widget that is insensitive (meaning its 
function is unavailable), though in practice the effect is quite similar.) The label and border 
of an insensitive button are dimmed; the background of a busy button is filled with a stippled 

pattern. 
The ButtonStack widget is similar to the OblongButton but invokes a menu rather than a 
single command. Clicking on it with one mouse button (usually Button 3) pops up a menu 
(which may in turn include other ButtonStack widgets, for cascading popups.) Clicking on 
the ButtonStack with another mouse button (usually Button 1) activates the default item for 
the menu. Visually, a ButtonStack is differentiated from an OblongButton by the presence of 
an arrowhead that points in the direction that the menu will pop up.J" 

In addition, there is an AbbrevStack widget, which performs similar functions as the Button- 
Stack widget, but shows up only as a small unlabelled box with the default choice for the 
menu displayed beside it. 

Exclusive and Nonexclusive Settings 

The Athena Toggle widget provides the concept of a button that establishes a setting (for 
example, sets an application resource) instead of performing an action. It highlights itself 
when selected, but remains highlighted until selected again. However, in the Athena Widget 
set, there is no visual distinction between a Command widget and a Toggle widget. 
OPEN LOOK provides such a distinction. In contrast to OblongButton, which always indi- 
cates that an action will be performed, a RectButton indicates that an option setting will be 
chosen. This setting may be exclusive or nonexclusive, as determined by the RectButton 
widget itself, depending on whether the widget is managed by an Exclusives, or Nonex- 
clusives composite widget. The RectButton widget class will not work correctly unless man- 
aged by one of these two composite widgets. The Exclusives and Nonexclusives widgets are 
themselves usually children of a Menu or ControlArea widget. 
In an Exclusives widget, RectButton widgets are laid out side by side in one or more col- 
umns. One or none of the RectButton widgets is chosen as the default, which is indicated by 
a double border. Once a RectButton is selected, it is shown with a dark border. The Exclu- 
sives widget makes sure that no more than one RectButton is selected at a time. 
In a Nonexclusives widget, RectButtons are displayed with separation between each button. 
As when used in an Exclusives widget, a dark border indicates that the option has been cho- 
sen. However, more than one button may be chosen at a time. 
Figure A-4 shows examples of exclusive and nonexclusive settings on menus. Note that, like 
the OblongButton, a RectButton may display a pixmap instead of a label. This makes the 
RectButton useful for a palette in a paint program. 
" In an earlier implementation of the toolkit, a ButtonStack widget had a double border on its bottom hall giving it 
the appearance of a stack of regular buttons. Hence its name, which is now merely historical. 
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Figure A-6. An OPEN LOOK Slider widget 

A.1.2 

A.1.2.1 

A.1.2.2 

Composite Widgets 

Composite widgets are in many ways the most important widgets in any widget set. They 
define the way that widgets work together, and they give consistency to an application. 

Menus and Control Areas 

As we've already discussed, command buttons of any kind are usually displayed as part of a 
menu or control area. 
Menus can either pop up below a ButtonStack or an AbbrevStack, or if the button is itself 
displayed on a menu, to the right, in a menu cascade. Figure A-4 showed examples of menus. 
The Menu widget is a pop-up widget created with XtCreatePopupShell (). It has a 
single child, which is a ControlArea widget. 
The ControlArea widget places its children in rows or columns. Resources allow the applica- 
tion to specify a fixed width and/or height, or a fixed number of rows or columns. Control- 
Area widgets are usually used as the parent of OblongButton, ButtonStack, Exclusives, or 
Nonexclusives widgets (which in rum manage RectButton widgets, as described in the next 
section). 

General Purpose Composite Widgets 

We've already discussed the Composite widgets relating to control areas and menus. How- 
ever, there are several general-purpose composite widgets in the OPEN LOOK set as well. 

The BulletinBoard widget provides a free-form area for placing subwindows. Widgets can 
be placed on a BulletinBoard at arbitrary x and y coordinates; if no coordinates are specified, 
they appear in the upper left comer. The BulletinBoard provides no management of its chil- 
dren, and is often used to establish the base frame for an application, since it allows the appli- 
cation programmer to place the major components of the application, rather than having to go 
by some Composite widget's arbitrary placement decisions. 

A BulletinBoard is often used as the main window of an application. 
The Form widget is a constraint widget similar to the Athena Form widget. It allows the 
placement of widgets to be specified relative to each other, and with rules goveming their 
separation or relative position. 
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A.1.2.3 

The Caption widget is like an Athena Label widget turned inside out. Like the Label widget, 
it prints a string. However, while the label widget's string is printed inside a visible widget 
border, a Caption string appears outside a bordered area. Caption is a composite widget 
class, and its label typically refers to a child widget of any size, which the Caption widget 
manages. The label can be aligned on either the fight, left, top or bottom of the child widget. 

The FooterPanel widget provides a consistent method for placing a footer along the bottom 
of another window. The footer panel takes two children. The top child is typically the main 
composite widget of the application; the bottom widget may contain a control or message 
area. The basic feature of the FooterPanel widget is that when the widget is resized, it 
applies all the change in the vertical direction to the top child, maintaining the bottom child 
at a constant height. 

Scrollbars and Scrollable Windows 

OPEN LOOK scrollbars use the visual metaphor of an elevator on a cable, but functionally 
they are similar to the Athena Scrollbar widget. The drag area (the thumb in an Athena 
Scrollbar widget) doesn't change size; instead, as shown in Figure A-7, there is a separate 
area that indicates the proportion of the data that is currently being displayed. Scrollbars 
may be oriented either horizontally or vertically. 

[ 
elevator _ 

top cable anchor 
up arrow 
drag area 
down arrow 
proportion indicator 

bottom cable anchor 

Figure A-7. An OPEN LOOK Scrollbar 
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Scrollbars are used as a component of a ScrolledWindow widget, which, like the Athena 
Viewport widget, provides a scrollable view of a data area in a child widget. The child 
widget is typically larger than the view area, but only the area in the parent's view area can 
be seen at any one time. Figure A-1 showed a ScrolledWindow widget as the main applica- 
tion pane. The ScrollingList widget displays a scrollable list of editable text fields, and pro- 
vides facilities for choosing and displaying one of the fields as "currently selected." Items 
can be selected from the list, changed, copied, and so on. This widget is useful for providing 
an interface to select a file for reading or writing. 

Figure A-8 shows a ScrollingList widget. 

Current Item border 
surrounding Current Item 

[ Appendix A 

Chapter 1 
Chapter 2 
Chapter 3 

scrollbar 

Figure A-8. An OPEN LOOK ScrollingList widget 

A.1.3 

Popups 

In addition to Menu widgets, the OPEN LOOK widget set contains three other special types of 
pop-up widgets: Notices, PopupWindows, and Help windows. A Notice is used to request 
confirmation or other information from the user. The widget contains a text area, where the 
message to the user is displayed, and a control area containing one or more buttons, one of 
which must be the default button. 
Figure A-9 shows an OPEN LOOK Notice widget. 
A Notice grabs the pointer. The only input allowed is to the Notice. Once the user has 
clicked a button, the Notice disappears. 
The second special pop-up type is a PopupWindow, which can be used for more complex 
popups. Unlike a Notice, which is a subclass of OverrideShell, a PopupWindowShell is a 
subclass of WMShell, and so is decorated by the window manager. It has all the visual attri- 
butes of a top-level window, including resize comers, etc. In addition, it displays a pushpin 
in the upper left comer. If the user clicks on the pushpin with the pointer, the menu doesn't 
go away when its action has been performed, but stays on the screen. This allows the user to 
keep menus (and other frequently-referenced popups, such as help screens) "pinned" on the 
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A.1.5 Drawing Areas 

Like the Athena widget set, the AT&T OPEN LOOK widgets provide no widget explicitly 
labeled as a drawing area. As described in this book, one is expected either to create a cus- 
tom widget for an application's main window, or to use a very basic widget class, and add 
actions for drawing. 

The AT&T OPEN LOOK widget set does include a Stub widget class (which is not docu- 
mented in the manual, but is included in the source), which is useful for providing a window 
for drawing. 

A.2 The OSF/Motif Widgets 

Figure A-12 shows the general look of a Motif application, the Motif Reference Editor, mre. 
mre, developed by Mitch Trachtenberg, was OSF demo software in Motif 1.1, but is no 
longer provided in the Motif distribution. 

File Edlt V_lw Q>t.loms _Compo _Sort P_an Help I 

[0]+ lusrlspoollmail/imui: 42 messages, 0 new, 0 unread, 0 deleted 

Folden [ lusrlspoollmai 11 lmui 

28 Eric Pearce 
29 Eric Pearce 
30 Eric Pearce 
31 Eric Pearce 
32 Eric Pearce 
33 Eric Pearce 
34 r Eric Pearce 
35 "ie Freedman" 
36 pr Rakesh Jain 
37 Lar Kaufman 
38 Eric Pearce 
39 "Mike Sierra" 
40 r Eric Pearce 
41 Eric Pearce 

Feb 20 2:44 (18) back cover flap 
Feb 20 10:48 (46) XCD and patch - this is i 
Feb 20 10:49 (16) gee wlz 
Feb 21 8:14 (17) back oover 
Feb 21 10:51 (21) "missing programs" 
Feb 21 11:34 (26) more problems 
Feb 21 8:37 (43) guess he doesn*t llke our 
Feb 22 11:11 (40) Re: back cover flap 
Feb 22 10:27 (54) Comments and help... 
Feb 22 12:38 (37) Re: trimming the "fat" fr 
Feb 22 9:52 (27) xcd 
Feb 22 5:25 (19) Recycllng totals 
Feb 22 4:10 (16) xarchle 
Feb 22 8:57 (60) vol 8 xcd backflap 

I Copyright 1990, 1991, 1992 Z-Code Software Corp. All rights reserved. 
New mall in /usr/spool/mall/imui: 
42 ! "Edie Freedman" Feb 23 9:51 (93) Re: vol 8 xcd backflap 

Figure A-12. Look of a Motif application 
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The List widget displays a list of strings set by the application and allows the user to select 
one or more of the strings. The selected data is passed to a callback function. (We'll talk 
more about this widget in the section on scrolling.) 

A.2.1.2 Analog Controls 

Motif's Scale widget is similar to OPEN LOOK's Slider but is more powerful since it can be 
used to display as well as to control analog values. 

RectObj 

Unnamed 

co. I 

ArrowButtonGadget 
LabelGadget 
SeparatorGadget 
ArrowButton 
Label 

I List 
Scrollbar 
Separator 
Text 
TextField 

BulletinBoard 
DrawingArea 
Frame 
PanedWindow 
RowColumn 
Scale 
ScrolledWindow 

I 
I 
I 
i 
i 

CascadeBuonGadget 
PushBuonGadget 
ToggleBuonGadget 
CascadeBuon 
DmwnBuon 
PushBuon 
ToggleBuon 

Form 
SelectionBox 
MessageBox 

MainWindow 
TopLevetSheil 
TrandentShel] 

KEY 

[- Motif 
[ - Xt Intrinsics 

Command 
FileSelectionBox 

OverrideShell MenuShell 
WMshe VendorShell 

DialogShell 

Figure A-13. C/ass inheritance hierarchy of the Motif widget set 
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Cancel 

Figure A-14. Motif DrawnButton and PushButton widgets 
Figure A-14 shows a DrawnButton and a PushButton. 

A.2.2 

A.2.2.1 

Composite Widgets 

As with OPEN LOOK, we've divided the discussion of Composite widgets into three areas: 
Menus and Control Areas, General-Purpose Composite Widgets, and Scrollable Windows. 
These distinctions are somewhat arbitrary and with menus the sections overlap with the one 
on popups, which appears later. 

Menus and Control Areas 

Motif provides a special Shell widget class called MenuShell for managing pop-up menus. 
However, most actual menu displays are managed by the RowColumn composite widget, 
which, like OPEN LOOK's ControlArea, displays buttons in rows or columns. 

Through resources, the RowColumn widget can be configured to create such specialized, 
predefined elements as a MenuBar (which can only accept CascadeButton widgets as chil- 
dren), several different styles of pulldown or pop-up menu panes, and several preconfigured 
control areas, such as a "Radio Box" containing multiple exclusive ToggleButton gadgets. 

Here you can begin to see the wide divergence in programming style made possible by the Xt 
Intrinsics. It is possible to create a hierarchy of relatively simple widgets to perform separate 
parts of a task, or a single, very complex widget which is highly configurable. In one of its 
incarnations, the RowColumn widget is equivalent to an OPEN LOOK ControlArea plus an 
Exclusives widget; in another, a ControlArea plus a Nonexclusives. 

In general, Motif widgets are more complex and have many more resources than widgets pro- 
vided in other widget sets. To simplify their use, though, Motif provides numerous conve- 
nience functions. For example, XmCreat:eladS.oBox ( ) will create a RowColumn widget 
with one specialized set of resources, while XmCreat:eMenuBar () will create one that is 
entirely different in appearance and function. 

Figure A-15 shows a RowColumn widget configured as a MenuBar and Figure A-16 shows 
one configured as a RadioBox (each with appropriate children). 
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Save As.. ^A 

E_xit . . E 

A.2.2.2 

Figure A-17. A Motif RowColumn widget configured as a drop-down window 
General Purpose Composite Widgets 

The BulletinBoard widget provides simple composite management, allowing widgets to be 
placed arbitrarily anywhere within its confines. The only constraint is that they are not 
allowed to overlap. 
The Form widget is a subclass of BulletinBoard that, like the widgets of the same name in 
other sets, allows children to be laid out relative to each other or to one or another of the 
sides of the Form. The children will thus always maintain their proper relative position when 
the application is resized. 
Figure A-18 shows a fully configured Form. 

Widget I at ::-: left comer 
. -_. . ::. 
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. 
_ 
Wi g.!' low ; Wid 
.... 
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 .. 
........ 
 _ 

Widget 2 right 
of Widget 1, and -  
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-- 
_ 
;i. ;m .. 
_ 

Figure A-18. A Motif Form widget and children 
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The Frame widget is used simply to provide a consistent border for widgets that might not 
otherwise have one. One use is to give a RowColumn widget a border with a 3-D appear- 
ance. 

A.2.2.3 

Scrollable Windows 

A Motif ScrollBar is illustrated in Figure A-19. 

Figure A-19. A Motif ScrollBar 

Like the Athena Scrollbar widget, the scrollbar has a "thumb" or slider that can be dragged 
up and down to scroll the associated window. You can also click above or below the thumb 
to move it a screenful at a time. Unlike the Athena widget, it also displays arrows at either 
end that can be used to scroll line by line. The associated window scrolls in the indicated 
direction as long as the pointer button is held down in one of the arrows. 
There are several different types of scrolling windows. The ScrolledWindow widget, like 
Athena's Viewport, provides a general mechanism for attaching scrollbars to some other 
window. 
The MainWindow widget is a subclass of ScrolledWindow with a special appearance 
reserved for application main windows. Figure A-14 showed a MainWindow widget. 
Using the XmCreateScrolledList ( ) function, a List widget can be created as a child 
of a ScrolledWindow, giving the effect of a simple scrolled list. In addition, there are several 
flavors of more complex scrolling lists. These include the SelectionBox widget, and its two 
subclasses, Command and FileSelectionBox. 
A general-purpose SelectionBox is akin to a ScrolledWindow/List combination, but adds a 
Text widget for entering additional data not on the list. The SelectionBox also adds at least 
three buttons labeled by default OK, Cancel, and Help. 
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Figure A-20 shows a SelectionBox. 
A FileSelectionBox is a SelectionBox specially designed to present a list of filenames for 
selections. A Command widget is a special kind of SelectionBox whose list consists of the 
history of commands entered in the Text widget. Each time a new command is entered, it is 
added to the history list. 

Items 

*Foreground ......................... black ' 
*activeForeground .................... black 
*activeBackground .................... gray 
*topShadowColor ..................... white 
*bottomShadowColor .................. black 

Selection 
I 

Edit- I , Add 

list box 

scrofl bars 
selection box 

push button 

A.2.3 

Figure A-20. A Motif SelectionBox 

Popups 

Motif defines two classes of Shell widgets: DialogShell, which is used for parenting Dialog 
boxes, and MenuShell, which is used for menus. These classes are rarely instantiated 
directly, but are instead created by convenience functions that also create their composite 
children. 

For example, functions exist to create a DialogShell with a variety of pre-configured 
MessageBox widgets as the visible child. 

As we've already discussed, a specially configured RowColumn widget is used to create a 
menu pane as the visible child of a MenuShell widget. 
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A.2.4 Text Widgets 

Like Athena and the AT&T OPEN LOOK widgets, Motif provides a Text widget that supports 
a complete editing command set. Like Athena, and unlike AT&T's OPEN LOOK widget set, 
both single- and multiline editing is supported by a single widget. But arranging for single- 
line editing is easier with Motif than with Athena. 

A.2.5 

Drawing Areas 

As you may recall, to do drawing in the Athena widgets we either created a custom widget or 
instantiated a Core widget in order to obtain a window for drawing. The Motif DrawingArea 
widget class answers this need in Motif. It provides a window for drawing and provides very 
simple, bulletin-board like composite management of children. 

Though the name of this widget class sounds promising, you should be aware that Motif 
really provides no more sophisticated drawing capabilities than Athena or the AT&T OPEN 
LOOK widget set. In each case, once you have selected the widget to draw on, you simply 
draw in its window using Xlib calls. 
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B 

Specifying Fonts and Colors 

This appendix describes the possible values for color, font, and geometry 
specifications. It also describes the font service and scalable font capabilities 
added in Release 5. 

In This Appendix: 
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B 
Specifying Fonts and Colors 

B.1 

This appendix describes the possible values for color, font, and geometry specifications. For 
fonts, it first describes basic font naming, and then the font service and scalable font capabili- 
ties added in Release 5. 

Color Specification 

Many clients have resources and command-line options that allow you to specify the color of 
the window background, foreground (the color that text or graphic elements will be drawn 
in), or window border. For example, the following resources might be set for a Label widget: 
*background: orange set the background color to orange 
*foreground: black set the foreground color to black 
*borderColor: black This must be Halloween t 
The corresponding command-line options have the form: 
-bg color Sets the background color 
-fg color Sets the foreground color 
-bd color Sets the border color 
Some clients allow additional options to specify color for other elements, such as the cursor, 
highlighting, and so on. 
By default, the background is usually white and the foreground black, even on color worksta- 
tions. You can specify a new color using either the names in the X Window System's color 
name database or hexadecimal values. 
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B.1.1 Color Names 

The rgb.txt file, usually located in/usr/lib/Xll on UNIX systems, is supplied with X and con- 
sists of predefined colors assigned to specific (but not necessarily intuitive) names.l" 

The following are some of the default color names that come with the X Window System. 
(See Appendix A, System Management, in Volume Three, X Window System User's Guide, 
Standard Edition, for information on customizing color name definitions.) This file is not 
part of the X standard, so vendors are free to modify it. However, most will just add to it, or 
redefine the values associated with each color name for better effects on their display hard- 

ware. 

aquamarine mediumaquamarine black blue 
cadetblue cornf lowerblue darkslateblue lightblue 
lightsteelblue mediumblue mediumslateblue midnightblue 
navyblue navy skyblue slateblue 
steelblue coral cyan firebrick 
gold goldenrod mediumgoldenrod green 
darkgreen darkolivegreen forestgreen limegreen 
mediumforestgreen mediumseagreen mediumspringgreen palegreen 
seagreen springgreen yel lowgreen darkslategray 
darkslategray dimgray dimgray lightgray 
lightgray khaki magenta maroon 
orange orchid darkorchid mediumorchid 
pink plum red indianred 
mediumvioletred orangered violetred salmon 
sienna tan thistle turquoise 
darkturquoise mediumturquoise violet blueviolet 
wheat white yellow greenyellow 

A number zero through three can be appended to each of these names in order to get various 
intensities of each color. In addition, a complete range of grays are provided by using the 
name gray or gray followed by a number from zero through 100. 
For example, the command line: 
% xterm -bg lightblue -fg darkslategray -bd plum & 
creates an xterm window with a background of light blue, foreground of dark slate gray, and 
border of plum. Note that the RGB values in the color database provided by MIT are correct 
for only one type of display; you may find that the color you get is not exactly what you 
expect given the name. To combat this, vendors may have corrected the RGB values to give 
colors closer to what the name implies. Or they may provide a device-independent color 
database. See Volume One, Xlib Programming Manual for more on device-independent 
color specification. 
At the command line, a color name should be typed as a single word (for example, dark- 
slategray). However, you can type the words comprising a color name separately if you 
enclose them in quotes, as in the following command line: 
% xterm -bg "light blue" -fg "dark slate gray" -bd plum & 

"tA corresponding compiled file called rgb.pag contains the definitions used by the server; the rgb.txt file is the 
human-readable equivalent. 

482 X Toolkit Intrinsics Programming Manual, Athena Edition 



B.1.2 Exact Color Specification 

B.1.2.1 

You can also specify exact colors using Xcms or using a hexadecimal color string. You prob- 
ably won't need this method unless you require a color not available by using a color name. 
Hexidecimal specifications are not recommended in R5 and later: use the device-independent 
style specification defined by Xcms instead. 
Haphazard use of exact colors potentially discourages the sharing of colors between applica- 
tions, thereby hastening the exhaustion of available color cells. 
In R5, the recommended way to specify specific RGB values is: 
 : <red> / <green> /<blue> 
Where red, green, and blue are each between 1 and 4 hexadecimal digits. Different primaries 
may be specified with different numbers of digits. If fewer than 4 digits are specified, they do 
not simply represent the most significant bits of the value; instead they represent a fraction of 
the maximum value. So the single digit 0xA does not mean 0xA000, but 10/15ths of 0xFFFF, 
or 0xAAAA. 
In R5 and later this form is understood by all the Xlib functions that accept color strings. 
In order to understand how this works, you may need a little background on how color is 
implemented on most workstations. 

The RGB Color Model 

Most color displays on the market today are based on the RGB color model. Each pixel on 
the screen is actually made up of three phosphors: one red, one green, and one blue. Each of 
these three phosphors is excited by a separate electron beam. When all three phosphors are 
fully illuminated, the pixel appears white to the human eye. When all three are dark, the 
pixel appears black. When the illumination of each primary color varies, the three phosphors 
generate a subtractive color. For example, equal portions of red and green, with no admix- 
ture of blue, makes yellow. 
As you might guess, the intensity of each primary color is controlled by a three-part digital 
value--and it is the exact makeup of this value that the hexadecimal specification allows you 
to set. 
Depending on the underlying hardware, different servers may use a larger or smaller number 
of bits (from 4 to 16 bits) to describe the intensity of each primary. To insulate you from this 
variation, clients are designed to take color values containing anywhere from 4 to 16 bits (l 
to 4 hex digits), and the server then scales them to the hardware. As a result, you can specify 
hexadecimal values in any one of the following formats: 
#RGB 
#RRGGBB 
#RRRGGGBBB 
#RRRRGGGGBBBB 
where R, G, and B represent single hexadecimal digits and determine the intensity of the red, 
green, and blue primaries that make up each color. 
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B.1.2.2 

When fewer than four digits are used, they represent the most significant bits of the value. 
For example, #3a6 is the same as #3000a0006000. 
What this means concretely is perhaps best illustrated by looking at the values that corre- 
spond to some colors in the color name database. We'll use 8-bit values (two hexadecimal 
digits for each primary) because that is the way they are defined in the rgb.txt file: 
#000000 black 
#FCFCFC white 
#FF0000 red 
#00FF00 green 
#0000FF blue 
#FFFF00 yellow 
#00FFFF cyan 
#FF00FF magenta 
#5F9F9F cadet blue 
#42426F cornflower blue 
#BFD8D8 light blue 
#8F8FBC light steel blue 
#3232CC medium blue 
#23238E navy blue 
#3299CC sky blue 
#007FFF slate blue 
#236B8E steel blue 
As you can see from the colors given above, pure red, green, and blue result from the corre- 
sponding bits being turned full on. All primaries off yields black, while all nearly full on 
gives white. Yellow, cyan, and magenta can be created by pairing two of the other primaries 
at full intensity. The various shades of blue shown above are created by varying the intensity 
of each primary--sometimes in unexpected ways. 
The bottom line here is that if you don't intimately know the physics of color, the best you 
can do is to look up existing colors from the color name database and experiment with them 
by varying one or more of the primaries till you find a color you like. Unless you need pre- 
cise colors, you are probably better off using color names. 
If you do specify a color using a hexadecimal value, try to use the same value for several 
applications so that they will share a color cell. 

How Many Colors Are Available? 

The number of distinct colors available on the screen at any one time depends on the amount 
of memory available for color specification. 

A color display uses multiple bits per pixel (also referred to as multiple planes or the depth of 
the display) to select colors. Programs that draw in color use the value of these bits as a 
pointer to a lookup table called a colormap, in which each entry (or colorcell) contains the 
RGB values for a particular color." As shown in Figure B-l, any given pixel value is used as 
an index into this table--for example, a pixel value of 16 will select the sixteenth colorcell. 

"l'There is a type of high-performance display in which pixel values are used directly to control the illumination of the 
red, green, and blue phosphors, but far more commonly, the bits per pixel are used indirectly, with the actual color 
values specified independently, as described here. 
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This implementation explains several issues that you might encounter in working with color 
displays. 

First, the range of colors possible on the display is a function of the number of bits available 
in the colon'nap for RGB specification. If 8 bits are available for each primary, then the 
range of possible colors is 256 3 (somewhere over 16 million colors). This means that you 
can create incredibly precise differences between colors. 

However, the number of different colors that can be displayed on the screen at any one time 
is a function of the number of planes. A four-plane system can index 2 4 colorcells (16 dis- 
tinct colors); an eight-plane system can index 2 8 colorcells (256 distinct colors); and a 
24-plane system can index 2 24 colorcells (over 16 million distinct colors). 

If you are using a four-plane workstation, the fact that you can precisely define hundreds of 
different shades of blue is far less significant than the fact that you can't use them all at the 
same time. There isn't space for all of them to be stored in the colormap at one time. 

Frame Buffer 
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Figure B-1. Multiple planes used to index a colormap 

This limitation is made more significant by the fact that X is a multiclient environment. 
When X starts up, usually no colors are loaded into the colormap. As clients are invoked, 
certain of these cells are allocated. But when all of the free colorcells are used up, it is no 
longer possible to request new colors. When this happens, you will usually be given the 
closest possible color from those that have already been allocated. However, you may 
instead be given an error message and told that there are no free colorcells. 

In order to minimize the chance of running out of colorcells, many programs use "shared" 
colorcells. Shared colorcells can be used by any number of applications, but they can't be 
changed by any of them. They can be deallocated only by each application that uses them, 
and when all applications have deallocated the cell, it is available for setting again. Shared 
cells are most often used for background, border, and cursor colors. 
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Alternately, some clients have to be able to change the color of graphics they have already 
drawn. This requires another kind of cell, called private, which can't be shared. A typical 
use of a private cell would be for the palette of a color mixing application. Such a program 
might have three bars of each primary color, and a box which shows the mixed color. The 
primary bars would use shared cells, while the mixed color box would use a private cell. 
In summary, some programs define colorcells to be read-only and shareable, while others 
define colorcells to be read/write and private. 
To top it off, there are even clients that may create a whole private colormap of their own, 
which will be swapped in by the window manager. Because of the way color is implemented, 
if this happens, all other applications will be displayed in unexpected colors. 
In order to minimize such conflicts, you should request precise colors only when necessary. 
By preference, use color names or hexadecimal specifications that you specified for other 
applications. 
For more information on color, see Chapter 7, Color, in Volume One, Xlib Programming 
Manual. 

B.2 Font Specification 

Most widgets that display text allow you to specify the font to be used in displaying text in 
the widget, via either the Xt2qfont resource, or the -fn and -font command-line options. 
The X Window System supports many different display fonts, with different sizes and type 
styles. (These are screen fonts and are not to be confused with printer fonts.) 

Adobe Systems, Inc., Digital Equipment Corporation, and others have contributed five fami- 
lies of screen fonts (Courier, Helvetica, New Century Schoolbook, Symbol and Times) in a 
variety of sizes, styles, and weights for 75 dots per inch monitors. Bitstream, Inc. contributed 
its Charter font family in the same sizes, styles, and weights for both 75 and 100 dots per inch 
monitors, plus outline versions of the same fonts. 

By default, standard fonts are stored in three directories: 

Directory 

/usr/lib/Xl 1/fonts/misc 
/usr/ lib/X l 1/fonts/75dpi 
/usr/lib/X l l /fonts/ l OOdpi 

Contents 

Six fixed-width fonts (also available in Release 2), 
the cursor font. 
Fixed- and variable-width fonts, 75 dots per inch. 
Fixed- and variable-width fonts, 100 dots per inch. 

These three directories (in this order) comprise X's default font path. The font path can be 
changed with the fp option to the xset client, as described in Volume Three, X Window Sys- 
tem User's Guide, Standard Edition. (The font path, together with other information about 
the server defaults, can be listed with xset query.) The font path may include font servers, 
which supply fonts over the network. All fonts in the font path can be listed with xlsfonts and 
fslsfonts, and the characters in a font can be displayed on the screen with xfd. 
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The names of each font file in the font directories has a filename extension of .snf, which 
stands for server natural format. Fonts are distributed in binary distribution format (bdf) in 
Release 4, and need to be compiled for a given server. Fonts are distributed in portable com- 
piled format (pcf) in Release 5, and do not need compiling. 

B.2.1 

Font Naming Conventions 

If you do a listing of any of the current font directories, you'll notice that the filenames have 
.snf or .pdf extensions. However, font names are not determined by the names of the files in 
which they are stored. 
Now, a font's name is determined by the contents of the font property named FONT rather 
than the name of the file in which the font is stored. 
If you run xlsfonts, you'll get an intimidating list of names similar to the one shown in Figure 
B-2. names are defined by the X Logical Font Description convention, also known as XLFD. 
The complete XLFD is reprinted in Volume Zero, X Protocol Reference Manual. Upon closer 
examination an XLFD name contains a great deal of useful information. 

foundry weight set width 
-'b& '-lucida- ediurn'-r- o a'-s 
font family slant 

horizontal 
resolution 
(dpi) 
pixels | spacing character set 
.,I, I I 
s- 18-180-)5-75-p- 106-'iso8859-1' 
additional vertical 
style resolution 
(dpi) 
points average width 
(in tenths of a point) (in tenths of a pixel) 

Figure B-2. A font name 

This rather verbose line is actually the name of the font stored in the file courBOlO (in the 
75dpi directory). This font name specifies the foundry (Adobe), the font family (Courier), 
weight (bold), slant (Oblique), set width (normal), size of the font in pixels (10), size of the 
font in tenths of a point (100--measured in tenths of a point, thus equals 10 points), horizon- 
tal resolution (75dpi), vertical resolution (75dpi), spacing (m, for monospace), average width 
in tenths of a pixel (60--measured in tenths of a pixel, thus equals 6 pixels) and character set 
(iso8859-1). 

'A property is a piece of information associated with a window or a font. See Volume One, Xlib Programming 
Manual, for more information about properties. 
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The meaning of many of these statistics is obvious. Some of the less obvious information is 

explained below. 
Foundry 

The type foundry (in this case, Adobe) that digitized and supplied the 
font. 
Set width A value describing a font's proportionate width, according to the foun- 
dry. Typical set widths include: normal, condensed, narrow, double 
width. All of the newer fonts have the set width normal. 
Pixels and points Type is normally measured in points, a printer's unit equal to 1/72 of an 
inch. The size of a font in pixels depends on the resolution of the display 
font in pixels. For example, if the display font has 100 dots per inch (dpi) 
resolution, a 12 point font will have a pixel size of 17, while with 75 dpi 
resolution, a 12 point font will have a pixel size of 12. 
Spacing Either m (monospace, i.e., fixed-width), p (proportional, i.e., variable- 
width), or c (charcell --a fixed-width font that conforms to traditional 
data processing character cell font model). 
Horizontal and vertical resolution 
The resolution in dots per inch that a font is designed for. Horizontal and 
vertical figures are required because a screen may have different capaci- 
ties for horizontal and vertical resolution. 
Average width Mean width of all characters in the font, measured in tenths of a pixel, in 
this case 6 pixels. 
Character set ISO. the International Standards Organization, has defined character set 
standards for various languages. The iso8859-1 in Figure B-2 represents 
the ISO Latin 1 character set, which is used by all of the fonts in the 
75dpi and lOOdpi directories. The ISO Latin 1 character set is a superset 
of the standard ASCII character set, which includes various special char- 
acters used in European languages other than English. See Appendix H 
of Volume Two, Xlib Reference Manual, for a complete listing of the 
characters in the ISO Latin 1 character set. 
This font-naming convention is intended to allow for the unique naming of fonts of any style, 
resolution and size. It is powerful, but unwieldy. 
To create a label widget that displays text in the font stored in the file courBOlO, you could 
use the resource setting: 
*label: -adobe-courier-bold-o-normal--lO-lOO-75-75-m-60-iso8859_l 
Developers can specify default fonts using a complete font name. However, requiring users 
to type a font name of this length is neither desirable nor practical. The X Window System 
developers have provided two alternatives: wildcarding and aliasing. 
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B.2.2 Font Name Wildcarding 

Any unnecessary part of a font name can be "wildcarded" by specifying a question mark (?) 
for any single character and an asterisk (*) for any group of characters. 
For example, using a wildcarded font name, the resource specification above could be written 
as follows: 
*label : *courier-bold-o-*- 10 O* 
(Note that when using wildcards with the -fn command line option, you must take care to 
quote the font names, since the UNIX shell has special meanings for the wildcard characters * 
and ?. This can be done by enclosing the entire font name in quotes, or by escaping each 
wildcard character by typing a backslash before it.) 
. 
If more than one font in a given directory matches a wildcarded font name, the server 
chooses the font to use. If fonts from more than one director)" match the wildcarded name, 
the server will always choose a font from the directory that is earlier in the font path. Thus. if 
a wildcarded font name matches a font from both the 75dpi and lOOdpi directories, and the 
75dpi directory comes first in the font path, the server chooses the font from that directory. 
In creating a wildcarded font name, you need to decide which parts of the standard font name 
must be explicit and which parts can be replaced with wildcards. As the previous example 
illustrates, you can use a single wildcard character for multiple parts of the font name. For 
instance, the final asterisk in the example stands for the sequence: 
-75-75-m-60-iso8859-1 
in the explicit font name. The idea is to specify enough parts of the font name explicitly so 
that the server gives you the font you have in mind. 
It's helpful to familiarize yourself with the available font families, weights, slants, and point 
sizes. The following list gives these statistics for the fonts in the directories 75dpi and 
lOOdpi in the standard X distribution from MIT.'t" (The fonts in the misc directory are hold- 
overs from Release 2 and have short, manageable names that should not require wildcarding.) 
Font families Charter, Courier, Helvetica, New Century Schoolbook, Symbol, Times 
Weights Medium, bold 
Slants Roman (r), an uptight design 
Italic (i), an italic design slanted clockwise from vertical 
Oblique (o), an obliqued upright design, slanted clockwise from vertical 
Point sizes 8, 10, 12, 14, 18, 24 
If you're unfamiliar with the general appearance of a particular font family, try displaying 
one of the fonts with xfd, as described in Volume Three, X Window System User's Guide, 
Standard Edition. 

For fonts other than those shipped by MIT, other families, weights, slants, point sizes, etc., may apply. 
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servers and X terminals will continue to support file-based fonts along with their support for 
font servers. 
The Font Service Protocol was designed by Jim Fulton of Network Computing Devices. The 
font server in the MIT distribution was implemented primarily by Dave Lemke, also of NCD. 
In addition, Apple Computer has donated a font server (which runs only on the Apple Macin- 
tosh computer) to export the Apple bitmap fonts, and, if available, the Apple TrueType fonts 
as well. 
Typically, a font server will run on one host per site and will export all the fonts available at 
the site, but there are a variety of other ways that font service can be configured. A large site 
may choose to have multiple font servers to prevent overloading of a single server or to pro- 
tect against service outages caused by network trouble or server crashes. A font server could 
export fonts parsed from a variety of formats, or a separate server could be used for each for- 
mat. A vendor of fonts with a custom format might provide a special font server to export 
those fonts, and might use the special server to implement licensing policies--restricting the 
maximum number of simultaneous users of a font, for example. Finally, note that in the ter- 
minology of X font service, the X server is a font client, and that it is perfectly legal to have 
other font clients such as printer drivers. Figure B-3 shows a font server providing service to 
a workstation, an X terminal, and a printer driver. 

eryer Maehina 
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Service Service 
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XI..JstFonts 

Load Font 

XLoadFont 

Client I Client 
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.75. I 1.0.0 I msc Icustom 175 lOO " |l 
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Figure B-3. A typical font server configuration 
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B.4.1 

low-resolution font. The fonts shipped by MIT for Release 5 include several "outline fonts" 
which describe characters by their component curves rather than by individual pixels. This 
description allows for successful scaling to any desired point size and resolution. The font 
server shipped by MIT in Release 5 has the capability to read and scale these outline fonts, 
and therefore the number of fonts available to the user is greatly increased. (Note, however, 
that a good bitmap font that is "hand-tuned" to a particular point size and screen resolution 
will generally be better looking than an outline font scaled to that size and resolution. Font 
design is an art, and the human touch is still important.) 

The following two sections apply equally to all scalable and scaled fonts, whether outline or 
bitmap, from the X server or the font server. 

Finding Scalable Fonts 

Supporting scalable fonts raises some important questions about the behavior of the Xlib 
function XListFonts (). First, since there are (theoretically) an infinite number of point 
sizes and resolutions that a font could be scaled to, it is no longer possible to list all available 
fonts in all available sizes. So some special syntax is needed to indicate that a font is scal- 
able and is available in any desired size, even if that size is not listed. But backwards compa- 
tibility is also an issue--the new point sizes provided by scalable fonts should not be hidden 
from existing pre-R5 applications. 
These seemingly contradictory goals are resolved by changing the semantics of the call to 
XListFonts ( ) and by extending the X Logical Font Description Conventions slightly.- 
In R5, scalable fonts are returned by XListFonts ( ) with the string "'0'" in the PIXEL_SIZE, 
POINT_SIZE, and AVERAGE_WIDTH fields (the seventh, eighth, and twelfth fields of the 
14-field XLFD font name). Non-scalable fonts will never have these three fields zero. and 
therefore these fields are sufficient to distinguish scalable from non-scalable fonts. Most font 
servers will list a few specific derived instances of each scalable font at standard sizes and 
resolutions for the benefit of older X applications that expect to find font names in this form. 
The X server and font server are only required to match scalable fonts when the font name 
pattern they are passed is a well-formed one. A well-formed font name is one that contains 
all 14 hyphens specified in the XLFD convention. Wildcards are permitted for any field, but 
may not replace multiple fields--all fields must be present in the name. For example: 
*-helvetica-bold-o-*-*-*-120-* 
is not a well-formed name, but 
- * -helvet ica-bold-o-* - * - *-12 0-75-75-* -* - is 08 859 -1 
is well-formed. Shortcut names specified as in the first example have come into common use, 
but with the increasing variety of display resolutions and fonts with non-standard charsets, it 
is good practice to specify these extra fields, even if you are not interested in using scaled 
fonts. If XListFonts () is passed a pattern that is not well-formed, it may not include 
scalable fonts in the search at all. 

%The XLFD Conventions are printed as Appendix M of X Protocol Reference Manual, Volume Zero of the O'Reilly 
& Associates series of X books. 
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Example B-2. Finding derived instances of scalable fonts 
/* Load a 12-point bold helvetica font defined at a 100xl00 dpi 
* resolution. The actual font loaded might be a derived instance of a 
* scalable font, or it might be a bitmap font--there is no way to 
* distinguish them. 
*/ 
font = XLoadFont (dpy, "-*-helvetica-bold-r-*-*-*-120-100-100-*-*-iso8859-1") ; 
/* Load a 20 pixel high helvetica font defined at 100xl00 dpi */ 
font2 = XLoadFont (dj, "-*-helvetica-medium-r-*-*-20-*-100-100-*-*-iso8859-1") ; 
/* List all 13-point Latin-I helvetica fonts defined at a I06x97 dpi 
* resolution. This pattern will match derived instances of scalable 
* fonts, and will probably only match derived instances of scalable 
* fonts, because there are not likely to be bitmap fonts defined at this 
* particular size and resolution. 
*/ 
list = XListFonts(dpy,'-*-helvetica-*-*-*-*-*-130-106-97-*-*-iso8859-1", 
50, &count) ; 
There are a number of reasons that a font name pattern could fail to match derived instances 
of scalable fonts. It is difficult to devise an algorithm that will correctly match scalable fonts 
against any font name pattern. For this reason, the X server or font server is not required to 
include scalable fonts in its search if the pattern it is given is not well-formed. A well- 
formed pattern must contain 14 hyphens. Note in particular that the first character in a well- 
formed name must be a hyphen. 
An underspecified font name will not match any derived instances of scalable fonts. This is 
because your font name could match any number of derived instances, and it is not possible 
to list them all. When only the point size and pixel size are specified, for example, they are 
enough together to determine the desired y-resolution for the font, but any x-resolution (and 
therefore any average width) is still possible. To uniquely match a derived instance, you'd 
have to specify the x-resolution of your screen or a desired average width for the font. The 
MIT implementation, however, makes reasonable guesses for unspecified resolution values. 
so underspecified font names do not occur. If only point size is specified, then default resolu- 
tions (75 or 100 dpi) are used. If both point and pixel size are specified as above, then the 
y-resolution they specify is used for both x- and y-resolution fields. 
Similarly, an overspecified font name, one with point size, pixel size, and x- and y-resolu- 
tions, for example, may not match any derived instances of scalable fonts: if the specified 
y-resolution is different from the y-resolution implicitly defined by the combination of point 
size and pixel size, then there is no way that the font can be scaled to satisfy your request. 
Example B-3 shows font name patterns that will fail to match any derived instances of scal- 
able fonts. 

Example B-3. Font name patterns that don't match scaled fonts. 
/* List 15-point bold oblique helvetica fonts. Derived instances of 
* scalable fonts will probably not be included in the list because the 
* pattern does not have all 14 fields. 
*/ 
helvboldl5 = XListFonts (dpy, "*-helvetica-bold-o-*-*-*-150-*', 50, &count) ; 

/* List all 17-point, 17-pixel bold oblique helvetica fonts defined at 
* 100dpi x- and y-resolutions. This pattern will not match any derived 
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Examp B-5. Loading a defivedsnce ofa scab nt 
/. 
* This routine is passed a scalable font name and a point size. It returns 
* an XFontStruct for the given font scaled to the specified size and the 
* exact resolution of the screen. The font name is assumed to be a 
* well-formedXLFDname, and to have pixel size, point size, and average 
* width fields of "0" and arbitrary x-resolution and y-resolution fields. 
* Size is specified in tenths of points. Returns NULL if the name is 
* malformed or no such font exists. 
*/ 
XFontStruct *LoadQueryScalableFont(dpy, screen, name, size) 
Display *dpy; 
int screen; 
char*name; 
int size; 
{ 
int i,j, field; 
char newname[500]; /* big enough for a long font name */ 
int res_x, res_y; /* resolution values for this screen */ 

/* catch obvious errors */ 
if ((name == NULL) II (name[0] != '-')) return NULL; 

/* calculate our screen resolution in dots per inch. 25.4n = 1 inch */ 
res_x = DisplayWidth(dpy, screen)/(DisplayWidthMM(dpy, screen)/25.4); 
res_y = DisplayHeight(dpy, screen)/(DisplayHeightMM(dpy, screen)/25.4); 

/* copy the font name, changing the scalable fields as we do so */ 
for(i = j = field = 0; name[i] != '\0' && field <= 14; i++) { 
newname[j++] = name[i]; 
if (name[i] == '-') { 
field++; 
switch(field) { 
case 7: /* pixel size */ 
case 12: /* average width */ 
/* change from "-0-" to "-*-" */ 
newname[j ] = '*' ; 
j++; 
if (name[i+l] != '\0') i++; 
break; 
case 8: /* point size */ 
/* change from "-0-" to "-<size>-" */ 
sprintf(&newname[j ], "%d", size); 
while (newname[j] != '\0') j++; 
if (name[i+l] != '\0') i++; 
break; 
case 9: /* x-resolution */ 
case i0: /* y-resolution */ 
/* change froman unspecified resolution to res_x or res_y */ 
sprintf(&newname[j ], "%d", (field == 9) ? res_x : res_y); 
while(newname[j] != "\0') j++; 
while((name[i+l] != '-') && (name[i+l] != '\0')) i++; 
break; 
} 

} 
newname[j ] = '\0'; 

/* if there aren't 14 hyphens, it isn't a well formed name */ 
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Table B- 1. Geometry Specification: x and y Offsets (continued) 

Offset Variables 

-xoff 

-yoff 

Description 

A negative x offset specifies the distance that the right edge of the win- 
dow is offset from the right side of the display. 
A negative y offset specifies the distance that the bottom edge of the 
window is offset from the bottom of the display. 

For example, the command line: 
% xclock -geometry 125x125-i0+i0 & 
places a clock 125x 125 pixels in the upper-right corner of the display, 10 pixels from both 
the top and the right edge of the screen. 
For xterm, the size of the window is measured in characters and lines. (80 characters wide by 
24 lines long is the default terminal size.) If you wanted to use the vtl00 window in 132- 
column mode, with 40 lines displayed at a time, you could use the following geometry op- 
tions: 
% xterm-geometry 132x0-i0+350 & 
This will place an xterm window 132 characters wide by 40 lines long in the lower-right cor- 
ner, 10 pixels from the right edge of the screen and 350 pixels from the top of the screen. 
Some clients may allow you to specify geometry strings for the size and position of the icon 
or an alternate window, usually through resources (in an .Xdefaults or other resource file). 
See the appropriate client reference pages in Part Three of Volume Three. X Vindo," System 
User's Guide, Standard Edition. for a complete list of available resources. 
You should be aware that, as with all user preferences, you may not always get exactly what 
you ask for. Clients are designed to work with a window manager, which may have its own 
rules for window or icon size and placement. However. priority is always given to specific 
user requests, so you won't often be surprised. 
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C 

Naming Conventions 

This appendix describes a suggested set of conventions for naming widgets, 
and elements within widget code. 



D 

Release Notes 

This appendix summarizes the changes between Release 4 and Release 5 
of the X Toolkit. 



in <Xll/lntrinsic.h> is that programs that unknowingly relied on macro definitions of 
index or st:rchr from <Xll/Xos.h> will now fail to compile. These programs may be 
compiled with the -DXT_BC flag which will restore the pre-Xl IR5 behavior. Substantial 
effort has been put into the MIT X 11R5 implementation to make it comply with ANSI-C and 
POSIX standards. New standard header files have been defined that make it easier to write 
portable X applications. They are <Xll/Xfuncs.h>, <Xll/Xfuncproto.h>, and <Xll/Xos- 
defs.h>. See the Third Edition of Volume One, Xlib Programming Manual for more informa- 
tion on these files. 
All references to the type caddr_l: have been changed to Xlzl:'of.nlzer because caddr_l: 
is not part of the ANSI-C standard. 
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E 

The xbitmap Application 

This appendix shows the complete code for the BitmapEdit widget and a rel- 
atively complex version of xbitmap, which is described in Chapter 4, An 
Example Application. 
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E 
The xbitmap Application 

This appendix shows the complete code for the BitmapEdit widget (without selections), and 
for an advanced version of the xbitmap application (xbitmap5 in the example distribution) 
which is similar to xbitmap3 described in Chapter 4 except that it both reads and writes X 11 
bitmap files (xbitmap3 was capable of writing them only). 

All source code from this book is available free from numerous sources, as described in the 
Preface. 

E.1 The BitmapEdit Widget 

Example E- 1. BitmapEdit: complete widget code 
/. 
* BitmapEdit.c - bitmap editor widget. 
*/ 
#include <Xll/IntrinsicP.h> 
#include <Xll/StringDefs .h> 
#include <stdio.h> 
#include "BitmapEdiP.h" 
#define ]2qTERNAL_WIDTH 2 
#define INTERNAL_HEIGHT 4 
#define DEFAULT_PIXMAP_WIDTH 
#define DEFAULT_PIXMAP_HEIGHT 
#define DEFAULT_CELL_SIZE 30 
/* values for instance variable is_drawn */ 
#define DRANN 1 
#define UNDRAWN 0 
/* modes for drawing */ 
#define DRAW 1 
#define UNDRAW 0 
#define MAXLINES I000 
#define SCROLIJARWIDTH 15 
#define DEFAULTWIITPH 300 

32 /* in cells */ 
32 /* in cells */ 

/* in pixels */ 

/*  of horiz or vertical cells */ 

/* widget size when showAll is False */ 
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Example E-1. BitmapEdit: complete widget code (continued) 

#define offset (field) XtOffset (BitmapEditWidget, field) 
static XtResource resources[ ] = { 
{ 
XtNforeground, 
XtCForeground, 
XtRPixel, 
sizeof (Pixel), 
offset (bitmapEdit. foreground), 
XtRString, 
XtDefaultForeground 
}, 
{ 
XtNcallback, 
XtCCallback, 
XtRCallback, 
sizeof (XtPointer), 
offset (bitmapEdit. callback), 
XtRCallback, 
}, 
{ 
XtNcellSizeInPixels, 
XtCCellSizeInPixels, 
XtRInt, sizeof (int), 
offset (bitmapEdit. cell_size_in_pixels), 
XtRInmediate, 
(Xt Pointer ) DEFAULT_CELL_SI ZE 
}, 
{ 
XtNpixmapWidthInCel i s, 
XtCPixmapWidthInCel i s, 
XtRDimension, 
sizeof (Dimension), 
offset (bitmapEdit .pixmap_width_in_cells), 
XtRImmediate, 
(Xt Pointer) DEFAULT_PIXMAP_WIDTH 
}, 
{ 
XtNpixmapHeight InCel i s, 
XtCPixmapHeight InCel i s, 
XtRDimension, 
sizeof (Dimension), 
offset (bitmapEdit .pixmap_height_in_cells), 
XtRImnediate, 
(Xt Point er) DEFAULT_PIXMAP_HEIGHT 
}, 
{ 
XtNcurX, 
XtCCurX, 
XtRInt, 
sizeof (int), 
offset (bitmapEdit. cur_x), 
XtRInmediate, 
(XtPointer) 0 
}, 
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Example E- 1. BitmapEdit: complete widget code (continued) 

{ 
XtNcurY, 
Xt CCurY, 
XtRInt, 
sizeof (int), 
offset (bitmapEdit. cur_y), 
XtRString, 
(XtPointer) NULL 
), 
{ 
XtNcel iArray, 
XtCCel iArray, 
XtRString, 
sizeof (String), 
offset (bitmapEdit. cell), 
XtRInediate, 
(XtPointer) 0 
), 
{ 
XtNshowEnt ireBitmap, 
XtCShowEntireBitmap, 
XtRBoolean, 
sizeof (Boolean), 
offset (bitmapEdit. showAl i), 
XtRInediate, 
(XtPointer) TRUE 
), 

/* Declaration of methods */ 

static void Initialize () ; 
static void Redisplay ( ) ; 
static void Destroy ( ) ; 
static void Resize ( ) ; 
static Boolean SetValues ( ) ; 
static XtGeometryResult QueryGeometry ( ) ; 

/* these Core methods not needed by BitmapEdit: 
* 
* static void ClassInitialize(); 
* static void Realize(); 
*/ 

/* the following are private functions unique to BitmapEdit */ 
static void DrawPixmaps(), DoCell(), ChangeCellSize(); 

/* the following are actions of BitmapEdit */ 
static void DrawCell(), UndrawCell(), ToggleCell(); 

/* The following are public functions of BitmapEdit, declared extern 
* in the public include file: */ 
char *BitmapEditGetArrayString(); 

static char defaultTranslations[ ] = 
"<BtnlDown>: DrawCell() \n\ 
<Btn2Down>: UndrawCell() \n\ 
<Btn3Down>: ToggleCell() \n\ 
<BtnLMotion>: DrawCell() \n\ 
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Example Eo 1. BitmapEdit: complete widget code (continued) 

<Btn2Motion>: UndrawCell ( ) \n\ 
<Btn3Motion>: ToggleCell ( ) "; 

static XtActionsRec actions [ ] = { 
{ "DrawCell", DrawCell}, 
{ "UndrawCell", UndrawCell }, 
{"ToggleCell", ToggleCell}, 
}; 

/* definition in BitmapEdit.h */ 
static BitmapEditPointInfo info; 

BitmapEditClassRec bitmapEditClassRec = { 

}; 

{ 
/* core_class fields */ 
/* superclass */ (WidgetClass) &coreClassRec, 
/* class_name */ "BitmapEdit", 
/* widget_size */ sizeof(BitmapEditRec), 
/* class_initialize */ , 
/* class_part_initialize */ NULL, 
/* class_inited */ FALSE, 
/* initialize */ Initialize, 
/* initialize_hook */ , 
/* realize */ XtInheritRealize, 
/* actions */ actions, 
/* nunl_actions */ XtNumber(actions), 
/* resources */ resources, 
/* nunl_resources */ XtNumber(resources), 
/* xrnl_class */ NULLQUARK, 
/* compress_otion */ TRUE, 
/* compress_exposure */ XtExposeCompressMultiple, 
/* compress_enterleave */ TRUE, 
/* visible_interest */ FALSE, 
/* destroy */ Destroy, 
/* resize */ Resize, 
/* expose */ Redisplay, 
/* set_values */ SetValues, 
/* set_values_hook */ NULL, 
/* set_values_almost */ XtInheritSetValuesAlmost, 
/* get_values_hook */ NULL, 
/* accept_focus */ NIKL, 
/* version */ XtVersion, 
/* callback_private */ NULL, 
/* thtable */ defaultTranslations, 
/* query_gecmetry */ QueryGeometry, 
/* display_accelerator */ XtInheritDisplayAccelerator, 
I* extension *I NULL 
}, 
{ 

/* _field */ 0, 
}, 

WidgetClass bitmapEditWidgetClass = (WidgetClass) & bitmapEditClassRec; 
static void 
GetDrawGC(w) 
Widget w; 
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Example E-1. BitmapEdit: complete widget code (continued) 

BitmapEditWidget cw = (BitmapEditWidget) w; 
XGCValues values; 
XtGCMaskmask = GCForeground I GCBackground  GCDashOffset 
 GCDashList I GCLineStyle; 

/* 
* Setting foreground andbackground to 1 and 0 looks like a 
* kludgebut isn't. This GC is used for drawing 
* into a pixmap of depth one. Real colors are applied with a 
* separate GC when the pixmap is copied into the window. 
*/ 
values.foreground = i; 
values.background = 0; 
values.dashes = i; 
values.dash_offset = 0; 
values.line_style = LineOnOffDash; 

cw->bitmapEdit.drawc = XCreateOC(XtDisplay(cw), 
cw->bitmapEdit.big_picture, mask, &values); 

static void 
GetUndra%C(w) 
Widget w; 
{ 
BitmapEditWidget cw = (BitmapEditWidget) w; 
XGCValues values; 
XtGCMaskmask = GCForeground I GCBackground; 

/* this looks like a kludge but isn't. This GC is used for drawing 
* into a pixmap of depth one. Real colors are applied as the 
* pixmap is copied into the window. 
*/ 
values.foreground = 0; 
values.background = i; 

cw->bitmapEdit.undrawc = XCreateOC(XtDisplay(cw), 
cw->bitmapEdit.big_picture, mask, &values); 

static void 
GetCopyGC(w) 
Widget w; 
{ 
BitmapEditWidget cw= (BitmapEditWidget) w; 
XGCValues values; 
XtGCMaskmask = GCForeground  GCBackground; 

values.foreground = cw->bitmapEdit.foreground; 
values.background = cw->core.backgroundpixel; 

cw->bitmapEdit.copyc = XtGetGC(cw, mask, &values); 

/* ARGSUSED */ 
static void 
Initialize(treq, tnew) 
Widget treq, tnew; 
{ 
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Example E-I. BitmapEdit: complete widget code (continued) 
BitmapEditWidget new : (BitmapEditWidget) tnew; 
new->bitmapEdit.cur_x = 0; 
new->bitmapEdit.cur__v = 0; 

/* 
* 

Check instance values set by resources that may be invalid. 

if ((new->bitmapEdit.pixmap_width_in_cells < I) II 
(new->bitmapEdit.pixmap_height_in_cells < I)) { 
XtWarning("BitmapEdit: pixmapWidthand/or pixmapHeight is too 
small (using I0 x I0)."); 
new->bitmapEdit.pixmap_width_in_cells = I0; 
new->bitmapEdit.pixmap_height_in_cells = I0; 
} 

if (new->bitmapEdit.cell_size_iri_pixels < 5) { 
XtWarning("BitmapEdit: cellSize is too small (using 5)."); 
new->bitmapEdit.cell_size_iri_pixels = 5; 
} 

if ( (new->bitmapEdit.cur_x < 0) II (new->bitmapEdit.cur_y < 0) ) { 
XtWarning("BitmapEdit: cur_x and cur_y must be non-negative\\e 
(using 0, 0)."); 
new->bitmapEdit.cur_x = 0; 
new->bitmapEdit.cur__v = 0; 
} 

if (new->bitmapEdit.cell == NULL) 
new->bitmapEdit.cell = 
XtCalloc(new->bitmapEdit.pixmap_width_in_cells 
* new->bitmapEdit.pixmap_height_in_cells, sizeof(char)); 

new->bitmapEdit.pixmap_width_in_pixels = 
new->bitmapEdit.pixmap_width in cells * 
new->bitmapEdit.cell_size_iri_pixels; 

new->bitmapEdit.pixmap_height_in_pixels = 
new->bitmapEdit.pixmap_height_in_cells * 
new->bitmapEdit.cell_size_in_pixels; 

if (new->core.width == 0) { 
if (new->bitmapEdit.showAll == False) 
new->core.width = (new->bitmapEdit.pixmap_width_iri_pixels 
> DEFAULZTIDI) ? DEFAULqgTIDTH : 
(new->bitmapEdit. pixmap_width_iri_pixels) ; 
else 
new->core.width = new->bitmapEdit .pixmap_width_in_pixels; 
} 

if (new->core.height == 0) { 
if (new->bitmapEdit.showAll == False) 
new->core.height = (new->bitmapEdit.pixmap_height_iri_pixels 
> DEFAULqgTIDTH) ? DEFAULqgTIDTH : 
(new->bitmapEdit.pixmap_height_iri_pixels); 
else 
new->core.height = new->bitmapEdit.pixmap_height_iri_pixels; 
} 

CreateBigPixmap(new); 
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Example E-1. BitmapEdit: complete widget code (continued) 

GetDrawCyC (new) ; 
GetUndrawCyC (new) ; 
GetCopyGC (new) ; 

DrawIntoBigPixmap(new); 
} 

/* ARGSUSED */ 
static void 
Redisplay(w, event) 
Widget w; 
XExposeEvent *event; 
{ 
BitmapEditWidget cw = (BitmapEditWidget) w; 
register int x, y; 
unsigned int width, height; 
if (!XtIsRealized(cw)) 
return; 

if (event) { /* called from btn-event or expose */ 
x = event->x; 
y = event->y; 
width = event->width; 
height = event->height; 
} 
else { /* called because complete redraw */ 
x = 0; 
y = 0; 
width = cw->bitmapEdit.pixmap_width_in_pixels; 
height = cw->bitmapEdit.pixmap_height_in_pixels; 
} 

if (DefaultDepthOfScreen(XtScreen(cw)) == i) 
XCopyArea(XtDisplay(cw), cw->bitmapEdit.big_picture, XtWindow(cw), 
cw->bitmapEdit.copyc, x + cw->bitmapEdit.cur_x, y + 
cw->bitmapEdit.cur__v, width, height, x, y); 
else 
XCopyPlane(XtDisplay(cw), cw->bitmapEdit.big_picture, XtWindow(cw), 
cw->bitmapEdit.copyc, x + cw->bitmapEdit.cur_x, y + 
cw->bitmapEdit.cur__v, width, height, x, y, i); 

/* ARGSUSED */ 
static Boolean 
SetValues(current, request, new) 
Widget current, request, new; 
{ 
BitmapEditWidget curcw = (BitmapEditWidget) current; 
BitmapEditWidget newcw= (BitmapEditWidget) new; 
Boolean do_redisplay = False; 

if (ctrrcw->bitmapEdit.foreground != newcw->bitmapEdit.foreground) { 
XtReleaseGC (curcw, curcw->bitmapEdit, copyc) ; 
GetCopyGC (newcw) ; 
do_redisplay = True; 
} 

if ((curcw->bitmapEdit.cur_x != newcw->bitmapEdit.cur_x) II 
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Example E- 1. BitmapEdit: complete widget code (continued) 
(curcw->bitmapEdit.cur_y := newcw->bitmapEdit.cur_y) ) 
do_redisplay = True; 
if (curcw->bitmapEdit.cell_size_in_pixels != 
newcw->bitmapEdit, cell_size_in_pixels) { 
ChangeCellSize (curcw, newcw->bitmapEdit, cell_size_in_pixels) ; 
do_redisplay = True; 
if (curcw->bitmapEdit.pixmap_width_in_cells ! = 
newcw- >bitmapEdit. pixmap_width_in_ce i i s ) { 
newcw- >bi tmapEdi t. pixmap_width_in_ce i i s = 
curcw- >bitmapEdit. pixmap_width_in_cel i s; 
XtWarning( "BitmapEdit : pixmap_width_in_cells cannot be set\\e 
by XtSetValues. \n" ) ; 
if (curcw->bitmapEdit.pixmap_height_in_cells .,= 
newcw- >bitmapEdit. pixmap_height_in_cel i s ) { 
newcw- >bitmapEdi t. pixmap_height_in_cel i s = 
curcw- >bitmapEdit. pixmap_height_in_cel is; 
XtWarning ( "BitmapEdit: pixmap_height_in_cells cannot \ \e 
be set by XtSetValues.\n"); 
return do_redisplay; 

static void 
Destroy (w) 
Widget w; 
{ 
BitmapEditWidget cw = (BitmapEditWidget) w; 
if ( cw- >bi tmapEdi t. big_picture) 
XFreePixmap (XtDisplay (cw), cw->bitmapEdit .big_picture) ; 
if (cw- >bitmapEdi t. drawc ) 
XFreeGC (XtDisplay (cw), cw->bitmapEdit .drawc) ; 
if (cw- >bi tmapEdi t. undrawc ) 
XFreeGC (XtDisplay (cw), cw->bitmapEdit, undrawc) ; 
if (cw- >bitmapEdit. copyc ) 
XFreeGC (XtDisplay (cw), cw->bitmapEdit, copyc) ; 
/* NOTE., This should only free when the application didn't 
* allocate it. Need to add another. */ 
XtFree (cw->bitmapEdit. cell ) ; 

static void 
DrawCell (w, event) 
Widget w; 
XEvent *event; 
{ 
BitmapEditWidget cw = (BitmapEditWidget) w; 
DrawPixmaps(cw->bitmapEdit.drawc, DRAW, cw, event); 
} 

static void 
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Example E-1. BitmapEdit: complete widget code (continued) 

UndrawCell (w, event) 
Widget w; 
XEvent *event; 
{ 
BitmapEditWidget cw = (BitmapEditWidget) w; 
DrawPixmaps(cw->bitmapEdit.undraw_gc, UNDRAW, cw, event); 

static void 
ToggleCell (w, event) 
Widget w; 
XEvent *event; 
{ 
BitmapEditWidget cw = (BitmapEditWidget) w; 
static int oldx = -I, oldy = -I; 
GC gc; 
int mode; 
int newx, newy; 

/* This is strictly correct, but doesn't 
* see to be necessary */ 
if (event->type == ButtonPress) { 
newx = (cw->bitmapEdit.cur_x + ((XButtonEvent *)event)->x) / 
cw->bitmapEdit, cel l_s i ze_in_pixel s; 
newy = (cw->bitmapEdit.cur_y + ((XButtonEvent *)event)->y) / 
cw- >bitmapEdit. cel l_size_in_pixel s; 
} 
else { 
newx = (cw->bitmapEdit.cur_x + ((XMotionEvent *)event)->x) / 
cw->bitmapEdit, cel l_size_in_pixels; 
newy = (cw->bitmapEdit.cur_y + ((XMotionEvent *)event)->y) / 
cw- >bitmapEdit. cel l_size_in_pixel s; 
} 

if ((mode = cw->bitmapEdit.cell[newx + newy * 
cw->bitmapEdit.pixmap_width_in_cells ] ) == DRAWN) { 
gc = cw->bitmapEdit.undraw_gc; 
mode = UNDRAW; 
} 
else { 
gc = cw->bitmapEdit.draw_gc; 
mode = DRAW; 
} 

if (oldx .'= newx II oldy .'= newy) { 
oldx = newx; 
oldy = newy; 
DrawPixmaps(gc, mode, cw, event); 
} 

static void 
DrawPixmaps (gc, mode, w, event) 
GC gc; 
int mode; 
Widget w; 
XBut tonEvent *event; 
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Example E- 1. BitmapEdit: complete widget code (continued) 

BitmapEditWidget cw = (BitmapEditWidget) w; 
int newx : (cw->bitrmapEdit.cur_x + event->x) / 
cw- >bitmapEdit. cell_size_in_pixels; 
int newy = (cw->bitrmapEdit.cur_y + event->y) / 
cw- >bitmapEdit. cell_size_in_pixels; 
XExposeEvent fake_event; 

/* if already done, return */ 
if (cw->bitrmapEdit.cell[newx + newy * 
cw->bitmapEdit.pixmap_width_in_cells] == mode) 
return; 

/* otherwise, draw or undraw */ 
XFillRectangle(XtDisplay(cw), cw->bitmapEdit.big_picture, gc, 
cw->bitmapEdit.cell_size_in_pixels*newx + 2, 
cw->bitmapEdit.cell_size_in_pixels*newy + 2, 
(unsigned int)cw->bitmapEdit.cell_size_in_pixels - 3, 
(unsigned int)cw->bitmapEdit.cell_size_in_pixels - 3); 

cw->bitrmapEdit.cell [newx + newy * cw->bitrmapEdit.pixmap_width_in_cells ] 
-- mode; 
info.mode = mode; 
info.newx : newx; 
info. newy = newy; 

fake_event.x = cw->bitrmapEdit.cell_size_in_pixels * 
newx - cw->bitmapEdit.cur_x; 
fake_event.y = cw->bitrmapEdit.cell_size in pixels * 
newy - cw->bitmapEdit.cur_y; 
fake_event.width = cw->bitrmapEdit.cell_size_in_pixels; 
fake_event.height = cw->bitmapEdit.cell_size_in_pixels; 

Redisplay(cw, &fake_event); 
XtCallCallbacks(cw, XtNcallback, &info); 

CreateBigPixmap(w) 
Widget w; 
{ 
BitmapEditWidget cw= (BitmapEditWidget) w; 
/* always a 1 bit deep pixmap, regardless of screen depth */ 
cw->bitmapEdit.big_picture = XCreatePixmap(XtDisplay(cw), 
RootWindow(XtDisplay(cw), DefaultScreen(XtDisplay(cw))), 
cw->bitrmapEdit.pixmap_width_in_pixels + 2, 
cw->bitmapEdit.pixmap_height_in_pixels + 2, i); 

DrawIntoBigPixmap(w) 
Widget w; 
{ 
BitmapEditWidget cw= (BitmapEditWidget) w; 
int r_horiz_segments, n_vert_segments; 
XSegment segment[MAXLINES]; 
register int x, y; 

XFillRectangle (XtDisplay (cw), cw->bitmapEdit .big_picture, 
cw->bitrmapEdit.undraw_gc, 0, 0, 
cw->bitmapEdit, pixmap_widt h_in_pixel s 
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Example E-1. BitmapEdit: complete widget code (continued) 
Dimension w_temp_cell_size_inpixels, h_temp_cell_size_in_pixels; 
Dimension new_cel l_si ze_inpixel s; 
w_temp_cell_size_inpixels = cw->core.width / 
cw->bitmapEdit, pixmap_width_iri_cel i s; 
h_temp_cell_size_inpixels = cw->core.height / 
cw->bitmapEdit, pixmap_height_'h_cel is; 
if (w_temp_cell_size_inpixels < h_temp_cell_size_inpixels) 
new_cell_size_in_pixels = w_temp_cell_size_inpixels; 
else 
new_cell_size_inpixels = h_temp_cell_size_in_pixels; 
/* if size change mandates a new pixmap, make one */ 
if (new_cell_size_in_pixels '.= cw->bitmapEdit.cell_size_in_pixels) 
ChangeCellSize (cw, new_cell_size_inpixels) ; 
} 
} 
static void 
ChangeCellSize (w, new_cell_size) 
Widget w; 
int new_cell_size; 
{ 
BitmapEditWidget cw = (BitmapEditwidget) w; 
int x, y; 
cw->bitmapEdit.cell_size_in_pixels = new_cell_size; 
/* recalculate variables based on cell size */ 
cw->bitmapEdit.pixmap_width in pixels = 
cw- >bitmapEdit. pixmap_width_in_cel i s * 
cw- >bitmapEdit. cel l_si ze_in_pixels; 
cw- >bitmapEdi t. pixmap_height_in_pixe i s = 
cw->bitmapEdit.pixmap_height in cells * 
cw->bitmapEdit, cel l_size_in_pixel s; 
/* destroy old and create new pixmap of correct size */ 
XFreePixmap (XtDisplay (cw), cw->bitmapEdit .big_/Dicture) ; 
CreateBigPixmap (cw) ; 
/* draw lines into new pixmap */ 
DrawIntoBigPixmap (cw) ; 
/* draw current cell array into pixmap */ 
for (x = 0; x < cw->bitmapEdit.pixmap_width_in_cells; x++) { 
for (y = 0; y < cw->bitmapEdit.pixmap_height_in_cells; y++) { 
if (cw->bitmapEdit.cell[x + (y * 
cw->bitmapEdit.pixmap_width_in_cells) ] == DRAN) 
DoCell(cw, x, y, cw->bitmapEdit.draw_c); 
else 
DoCell(cw, x, y, cw->bitmapEdit.undraw_c); 
} 

static void 
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Example E-1. BitmapEdit: complete widget code (continued) 

DoCell(w, x, y, gc) 
Widget w; 
int x, y; 
GC gc; 
{ 
BitmapEditWidget cw = (BitmapEditWidget) w; 
/* otherwise, draw or undraw */ 
XFillRectangle (XtDisplay (cw), cw->bitmapEdit.big_picture, gc, 
cw->bitmapEdit.cell_size_in_pixels * x + 2, 
cw->bitmapEdit.cell_size_in_/Dixels * y + 2, 
(unsigned int) cw->bitmapEdit .cell_size_in_pixels - 3, 
(unsigned int) cw->bitmapEdit, cell_size_in_pixels - 3 ) ; 

static XtGecetryResult QueryGecetry(w, proposed, answer) 
Widget w; 
XtWidgettry *proposed, *answer; 
{ 
BitmapEditWidget cw = (BitmapEditWidget) w; 
answer->request_ode = CWWidth I CWHeight; 

/* initial width and height */ 
if (cw->bitmapEdit.showAll == True) 
answer->width = cw->bitmapEdit .pixmap_width_in_pixels; 
else 
answer- >width = (cw->bitmapEdit.pixmap_width_in_pixels > 
DEFAULTw-IDTH) ? DEFAULTw-IDTH : 
cw- >bitmapEdit. pixmap_width_in_pixel s; 

if (cw->bitmapEdit.showAll == True) 
answer->height = cw->bitmapEdit.pixmap_height_in_pixels; 
else 
answer->height = (cw->bitmapEdit.pixmap_height_in_pixels > 
DEFAULTWIDTH) ? DEFAULTWIDTH : 
cw->bitmapEdit.pixmap_height_in_pixels; 

if ( ((proposed->request_ode & (CWWidth I CWHeight)) 
== (CWWidth I CWHeight)) && 
proposed->width == answer->width && 
proposed->height == answer->height) 
return XtGecetryYes; 
else if (answer->width == cw->core.width && 
answer->height == cw->core.height) 
return XtGecetryNo; 
else 
return XtGecmetryAlmost; 
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E.2 The BitmapEdiP.h Private Header File 

Example E-2. BitmapEdiP.h: complete private header file 
/, 
* BitmapEditP.h - Private definitions for BitmapEdit widget 
*/ 

#i fndef _ORABitmapEdit P_h 
#define _ORABitmapEdit P_h 

/* 
* This include not needed unless the .c file includes IntrinsicP.h 
* after this file. Anyway, it doesn't hurt. 
*/ 
#include <Xll/CoreP.h> 

/* 
* This one is always needed! 
*/ 
#include "BitmapEdit.h" 
/* New fields for the BitmapEdit widget class record */ 
typedef struct { 
int make_compiler_happy; /* keep compiler happy */ 
} BitmapEditClassPart; 

/* Full class record declaration */ 
typedef struct _BitmapEditClassRec { 
CoreClassPart core_class; 
BitmapEditClassPart bitmapEdit_class; 
} BitmapEditClassRec; 

extern BitmapEditClassRec bitmapEditClassRec; 

/* New fields for the BitmapEdit widget record */ 
typedef struct { 
/* resources */ 
Pixel foreground; 
XtCallbackList callback;/* application installed callback function(s) */ 
Dimension pinap_width_in_cells; 
Dimension pinap_height_in_cells; 
int cell_size_in_pixels; 
int cur_x, cur__v; /* position of visible corner in big pixnap */ 
char *cell; /* array for keeping track of array of bits */ 
Boolean showAll; /* whether bitmap should d/splay entire bitmap */ 
/* private state */ 
Dimension pixmap_width_in_pixels; 
Dimension pixmap_height_in_pixels; 
Pinap big_picture; 
GC draw__gc; /* one plane, for drawing into pinap */ 
GC undraw__gc; /* one plane, for drawing into pixmap */ 
GC copy__gc; /* defaultdepthofscreen, for copying 
pixnap into window */ 
} BitmapEditPart; 

/* 
* Full instance record declaration 
*/ 
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Example E-2. BitmapEdiP.h: complete private header file (continued) 
typedef struct _BitmapEditRec { 
CorePart core; 
BitmapEditPart bitmapEdit; 
} BitmapEditRec; 
#endif /* _ORABitmapEditP_h */ 

E.3 The BitmapEdit.h Public Header File 

Example E-3. BitmapEdit.h: complete public header file 
#i fndef _ORABitmapEdit_h 
#define _ORABitmapEdit_h 
/* 
* BitmapEdit Widget public include file 
*/ 

/* 
* This include not needed unless the application includes 
* Intrinsic.h after this file. Anyway, it doesn't hurt. 
*/ 
#include <Xll/Core.h> 

Resources: 
Name Class RepType Default Value 

(frcm RectObj) 
ancestorSensitive 
x Position 
y Position 
width Dimension 
height Dimension 
borderWidth BorderWidth 
sensitive Sensitive 

Int 0 
Int 0 
Dimension 0 
Dimension 0 
Int 

( frcn windowObj ) 
screen Screen Pointer XtCopyScreen 
depth Depth Int XtCopyFrcnParent 
colormap Colormap Pointer XtCopyFrcm%Parent 
background Background Pixel White 
backgroundPixmap Pixmap Pixmap XtUnspeci fiedPixmap 
borderColor BorderColor Pixel Black 
borderPixmap BorderPixmap Pixmap XtUnspeci fiedPinap 

mappedWhenManagedMappedWhenManagedBoolean True 
translations 
accelerators 

(frcn Core) 
none 

(frcm BitmapEdit) 
foregroundPixel Foreground Pixel Black 
backgroundPixel Background Pixel White 
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Example E-3. BitmapEdit.h: complete public header file (continued) 

* callback Callback Callback NULL 
* cellSize CellSize Int 30 
* pixmapWidth PixmapWidth Int 32 
* pixmapHeight PixmapHeight Int 32 
*/ 

/* 
* This public structure is used as call_data to the callback. 
* It passes the x, y position of the cell toggled (in units of 
* cells, not pixels) and a mode flag that indicates whether the 
* cell was turned on (I) or off (0). 
*/ 
typedef struct { 
int mode; 
int newx; 
int newy; 
} BitmapEdit Point Info; 
#define XtNcellSizeInPixels "cellSizeInPixels" 
#define XtNpixmapWidthInCells "pixmapWidthInCells" 
#define XtNpixmapHeightInCells "pixmapHeightInCells" 
#define XtNcurX "curX" 
#define XtNcurY "curY" 
#define XtNcellArray "cellArray" 
#define XtNshowEntireBitmap "showEntireBitmap" 
#define XtCCellSizeInPixels "CellSizeInPixels" 
#define XtCPixmapWidthInCells "PixmapWidthInCells- 
#define XtCPixmapHeightInCells "PixmapHeightInCells. 
#define XtCCurX "CurX" 
#define XtCCAY "CurY" 
#define XtCCellArray "CellArray" 
#define XtCShowEntireBitmap . ShowEntireBitmap" 
extern char *BitmapEditGetArrayString ( ) ; /* w * / 
/* Widget w; */ 
/* Class record constants */ 
extern WidgetClass bitmapEditWidgetClass; 
typedef struct _BitmapEditClassRec *BitmapEditWidgetClass; 
typedef struct _BitmapEditRec *BitmapEditWidget; 
#endif /* _ORABitmapEdit_h */ 
/* DC'T ADD STUFF AFTER THIS #endif */ 
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E.4 xbitmap5 

Example E-4. xbitmap5: complete application code 
/. 
* xbitmap8, c 
*/ 
#include <Xll/Intrinsic. h> 
#include <Xll/StringDefs. h> 

#include <Xll/Xaw/Form. h> 
#include <Xll/Xaw/Box.h> 
#include <Xl l / Xaw / Ccrmmnd . h> 

#include "BitmapEdit .h" 
#include <stdio.h> 

#define DRANN 1 
#define UNDRANN 0 

GC drawc, undrawc, invertc; 
Pixmap normal_bitmap; 
Widget bigBitmap, showNormalBitmap, showReverseBitmap; 
Dimension pixmap_width_incells, pixmap_height_incells; 

static void cell_toggled(); 
String filename; /* filename to read andwrite */ 
static Boolean file_containedood_data = False; 

/* ARGSUSED */ 
static void 
Printout(widget, client_data, call_data) 
Widget widget; 
XtPointer client_data, call_data; /* unused */ 
{ 
XWriteBitmapFile(XtDisplay(widget), filename, normal_bitmap, 
pixmap_width_in_cells, pixmap_height_incells, 0, 0); 
} 

/*ARGSUSED*/ 
static void 
Redraw_small_picture(w, event, params, num_params) 
widget w; 
XEvent *event; 
String *params; 
Cardinal *num_params; 
{ 
GC gc; 
if (w == showNormalBitmap) 
gc = DefaultGCOfScreen(XtScreen(w)); 
else 
gc = invert_gc; 
if (DefaultDepthOfScreen(XtScreen(w)) == i) 
XCopyArea(XtDisplay(w), normal_bitmap, XtWindow(w), 
gc, 0, 0, pixmap_width_in_cells, 
pixmap_height_incells, 0, 0); 
else 
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Example E-4. xbitmap5: complete application code (continued) 
"XBitmap8", /* Application class */ 
table, XtNumber(table), /* cc[mnd line option list */ 
&argc, argv, /* cc[mnd line args */ 
NULL, /* for missing app-defaults file */ 
NULL) ; /* terminate varargs list */ 

if (argv[l ] .'= NULL) 
filename = argv[ 1 ] ; 
else { 

fprintf(stderr, "xbitmap: must specify filename on ccand line.\n'); 
exit (i) ; 

form = XtCreateManagedWidget ( "form", formWidgetClass, topLevel, NULL, 0) ; 
buttonbox = XtCreateManagedWidget ( "buttonbox', boxWidgetClass, form, 
NULL, 0); 

output = XtCreateManagedWidget("output", ccm%ndWidgetClass, buttonbox, 
NULL, 0); 

XtAddCallback(output, XtNcallback, Printout, NULL); 
quit = XtCreateManagedWidget("quit", ccm%ndWidgetCls, buttonbox, 
NULL, 0); 

XtAddCallback(quit, XtNcallback, exit, NULL); 
XtAppAddActions(app_context, window_actions, XtNumber(window_actions)); 
switch (XReadBitmapFile(XtDisplay(quit), 
RootWindowOfScreen(XtScreen(quit)), filename, 
&width, &height, &normal_bitmap, &junk, &junk)) { 
case BitmapSuccess: 
file_containedood_data = True; 
if ((pinap_width in cells != width) I 
(pinap_height_in_cells != height)) { 
fprintf(stderr, "xbitmap: bitmap file dimensions\ 
do not match resource database,\ 
ignoring database.\n"); 
i = 0; 
XtSetArg(args[i ], XtNpinapWidthInCells, width); i++; 
XtSetArg(args[i ], XtNpinapHeightInCells, height); i++; 
pinap_width in 9ells = width; 
pinap_height_in_cells = height; 
cell = FillCell(quit); 
XtSetArg(args [i ], XtNcellArray, cell); i++; 
} 
break; 
case BitmapOpenFailed: 
fprintf(stderr, "xbitmap: could not open bitmap file, using 
fresh bitmap.\n"); 
break; 
case BitmapFileInvalid: 
fprintf(stderr, "xbitmap: bitmap file invalid.\n"); 
exit(l); 
case BitmapNoMemory: 
fprintf(stderr, "xbitmap: insufficient server memory to 
create bitmap.\n"); 
exit(l); 
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Example E-4. xbitmap5: complete application code (continued) 
default : 
fprintf (stderr, "xbitmap: progranning error. \n" ) ; 
exit(l) ; 
) 
/* args are set in if and switch above if file was read */ 
bigBitmap = XtCreateMaagedWidget('bigBitmap', 
bitmapEditWidgetClass, form, args, i); 
XtAddCallback(bigBitmap, XtNcallback, cell_toggled, NULL); 
if ( ! file_containedood_data) { 
XtVaGetValues (bigBitmap, 
XtNpimapHeight InCel i s, &pimap_he ight_in_ce 11 s, 
XtNpixmapWidthInCe i i s, &pinap_width_in_ce 11 s, 
NULL); 
normal_bitmap = XCreatePimap(XtDisplay(quit), 
RootWindowOfScreen (XtScreen (quit)), 
pixmap_width_in_cells, pinap_height_in_cells, i) ; 
) 
set_up_things (topLevel) ; 
showNormalBitmap = XtVaCreateManagedWidget ( "showNormalBitmap", 
coreWidgetClass, buttonbox, 
XtNWidth, pimap_width_in_ce i i s, 
XtNheight, pi)ap_height_in_ce i i s, 
XtNtranslations, XtParseTranslat ionTable (trans), 
NULL) ; 
showReverseBitmap = XtVaCreat eManagedWidget ( "showReverseBitmap", 
coreWidgetClass, buttonbox, 
XtNWidth, pimap_width_in_ce i i s, 
XtNheight, pimap_height in cells, 
XtNtranslations, XtParseTranslationTable (trans), 
NULL) ; 
XtRealizeWidget (topLevel) ; 
XtAppMainIxp (app_context) ; 
) 
set_up_things (w) 
Widget w; 
{ 
XGCValues values; 
values, foreground = 1; 
values.background = 0; 
/* note that normal_bitmap is used as the draw-ble because it 
* is one bit deep. The root window may not be one bit deep. */ 
draw_gc = XCreateGC(XtDisplay(w), normal_bitmap, 
GCForeground [ OCBackground, &values); 
values.foreground = 0; 
values.background = 1; 
umIraw_gc = XCreateGC (XtDisplay (w), normal_bitmap, 
GCForeground [ OCBackground, &values); 
/* this GC is for copying from the bitmap 
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Example E-4. xbitmap5: complete application code (continued) 
* to the small reverse widget */ 
values, foreground = WhitePixelOfScreen (XtScreen (w)) ; 
values .background = BlackPixelOfScreen (XtScreen (w)) ; 
invert_gc = XtGetGC(w, GCForeground  GCBackground, &values); 
) 

/* ARGSUSED */ 
static void 
cell_toggled(w, client_data, info) 
Widget w; 
XtPointer client_data; /* unused */ 
XtPointer info; /* call_data (frcrn widget) */ 
{ 
BitmapEditPointInfo *cur_info = (BitmapEditPointInfo *) info; 
/* 
* Note: BitmapEditPointInfo is defined in BitmapEdit.h 
*/ 

XDrawPoint(XtDisplay(w), Drmal_bitmap, ((cur_info->mode == DRAWN) 
? draw_gc : undraw_gc), cur_info->newx, cur_info->newy) ; 
Redraw_small_picture (showNormalBitmap) ; 
Redraw_small_picture (showReverseBitmap) ; 
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F 

Sources of Additional Information 

This appendix describes where you can get more information about Xlib and 
about X in general, including other books on the subject and the various 
ways to get the source code for X. 
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F 
Sources of Additional Information 

This appendix lists a few of the official and unofficial sources for information about the X 
Window System and associated software. 
Note that some of this detailed information may become dated rather quickly. The best 
source of current information is the comp.windows.x network news group, described later in 
this appendix. 

F.1 

Getting the X Software 

At this writing, the current public release level is Release 5. This book documents Release 4 
and Release 5. Many people will continue to use R4 for a while, since there is a considerable 
lag time between the date that MIT distributes a new release and the date by which vendors 
integrate that release into their own products and issue updates. All changes to Xlib in R5 
are backwards compatible, although there are many new interfaces that provide additional 
capabilities. 

You can get the X software directly from MIT on three 9-track 1600-BPI magtapes written in 
UNIX tar format or on one 9-track 6250-BPI magtape, along with printed copies of MIT's 
manuals, by sending a check in U.S. currency for U.S. $400 to: 

MIT Software Distribution Center 
Technology Licensing Office 
MIT E32-300 
77 Massachusetts Avenue 
Cambridge, MA 02139 

Their telephone number is (617) 253-6966, and the "X Ordering Hotline" is (617) 258-8330. 
If you want the tapes and manuals shipped overseas, the price is $500. The manual set alone 
is $125, including U.S. shipping, or $175, including overseas shipping. 

Other distribution media or formats are not available from the MIT Software Distribution 
Center but are from other independent vendors such as ICS, mentioned later. The Release 
tape comes with source code for sample servers for Apollo, DEC, HP, IBM, Sun, and several 
other workstations, source code for clients written by MIT, sources for the toolkits Xt, 
XView, Interviews, and Andrew, contributed software written outside MIT, and sources and 
Postscript files for all MIT's documentation. Note that the servers supplied are sample 
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F.1.1.1 

F.1.1.2 

path 

You may put as many send commands as you like into one message to the server, 
but the more you ask for, the longer it will take to receive. See Section F. 1.1.2 for 
an explanation. Actually, it is not strictly true that you can put as many send com- 
mands as you want into one message. If the server must use UUCP mail to send 
your files, then it cannot send more than 100K bytes in one message. If you ask for 
more than it can send, then it will send as much as it can and ignore the rest. 

The path command exists to help in case you do not get responses from the server 
when you mail to it. 
Sometimes the server is unable to retum mail over the incoming path. There are 
dozens of reasons why this might happen, and if you are a true wizard, you already 
know what those reasons are. If you are an apprentice wizard, you might not know 
all the reasons, but you might know a way to circumvent them. 

If you put in a path command, then everything that the server mails to you will be 
mailed to that address rather than to the return address on your mail. The server 
host expo.lcs.mit.edu does not have a direct UUCP connection to anywhere; you 
must go through mit-eddie (the UUCP name of eddie.mit.edu) or somewhere else. 

Notes 

The xstuff server acknowledges every request by return mail. If you do not get a message 
back in a day or two, you should assume that something is going wrong and perhaps try a 
path command. 

The xstuff server does not respond to requests from users named root, system, daemon, or 
mailer. This is to prevent mail loops. If your name is "Bruce Root" or "'Jane Daemon" and 
you can document this, we will happily rewrite the server to remove this restriction. Yes, we 
know about Norman Mailer and Waverley Root. Norman doesn't use netmail and Waverley 
is dead. 

Fairness 

The xstuff server contains many safeguards to ensure that it is not monopolized by people 
asking for large amounts of data. The mailer is set up so that it will send no more than a fixed 
amount of data each day. If the work queue contains more requests than the day's quota, then 
the unsent files will not be processed until the next day. Whenever the mailer is run to send 
its day's quota, it sends the shortest requests out first. 

If you have a request waiting in the work queue and you send in another request, the new 
request is added to the old one (thereby increasing its size) rather than being filed anew. This 
prevents you from being able to send in a large number of small requests as a way of beating 
the system. 

The reason for all of these quotas and limitations is that the delivery resources are finite, and 
there are many people who would like to make use of the archive. 
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Table F-1. Consortium Members (continued) 

Siemens Nixdorf Informationssysteme AG 
Silicon Graphics Computer Systems 
Sony Corporation 
Sun Microsystems, Inc. 
Tandberg Data A/S 

Tektronix, Inc. 
Texas Instruments, Inc. 
Unisys Corp. 
Xerox Corporation 

Table F-2. Consortium Affiliates 

Adobe Systems 
AGE Logic, Inc. 
Aptronix, Inc. 
ASTEC, Inc. 
Athenix Corp. 
Bitstream, Inc. 
CETIA 
Chromatics 
Codonics, Inc. 
Industrial Technology Research 
Institute (China) 
Data Connection Ltd. 
Evans & Sutherland 
Frame Technology Corp. 
GIPSI S.A. (France) 
GfxBase 
HaL Computer Systems, Inc. 
Institute for Information 
Industry (Taiwan) 
Integrated Computer Solutions, Inc. 
Interactive Systems Corp. 
Ithaca Software 
IXI Limited 
Japan Computer Corporation 
Jupiter Systems 
KAIST (Korea Advanced Institute 
of Science and Technology) 
Labtam Australia 
Liant Software Corp. 
Locus Computing Corporation 

Megatek Corp. 
Metro Link, Inc. 
Metheus Corp. 
MIPS Computer Systems 
Mitre Corp. 
Objectivity, Inc. 
Open Software Foundation 
O'Reilly & Associates, Inc. 
PCS Computer Systeme GmbH (Germany) 
Peritek Corp. 
PsiTech, Inc. 
Quarterdeck Office Systems 
Ramtek Corp. 
Samsung Software America 
ShoGraphics, Inc. 
Snitily Graphics Consulting Services 
Solbourne Computer Inc. 
SOUM Corporation (Japan) 
SPARC International 
SpectraGraphics Corp. 
Stanford University 
Strategic Research Institute Inc. (Japan) 
Sumitomo Electric Workstation Corp. 
Tatung Science and Technology 
Tyan Computer 
Unipalm XTech 
University of Lowell 
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Table F-2. Consortium Affiliates (continued) 
VisionWare Ltd. 
Visix Software, Inc. 
Visual Information Technologies, Inc. 

Visual Technology, Inc. 
Widget, Inc. (Japan) 
X/Open Company Ltd. 

Most of these companies have or are preparing products based on X. 

F.5 

Finding Out for Yourself 

X is unusual in that the source code is freely copyable by anyone as long as the copyright 
notices are observed. It should be possible for most X programmers to get a copy of the X 
source code from the sources listed above. Once you understand how the code is organized, 
you can look up certain details about how X works as long as you have a good knowledge of 
C and a little persistence. In "Star Wars," the saying was "Use the Force, Luke." In X, it is 
"Use the Source, Luke." 
Xlib and the server are two distinct chunks of code. Each contains code for sending and 
receiving information to and from the other over the network using protocol requests, replies, 
events, and errors. The source tree as supplied on the X distribution tape places the Xlib 
source in the directory mit/lib/X, where mit is the top of the entire source tree. Their server 
source is placed in mit/server. 
The procedure for finding out something about an Xlib routine is normally to search for the 
routine in the Xlib code and then figure out what it does. Sometimes the answer can be found 
there. Many of the routines, however, simply place their arguments in a protocol request and 
send it to the server. Then you will have to look in the server code for the answer. To find 
the correct place in the server code, you will need the symbol for the protocol request, which 
is the first argument in the GetReq call. 
The server code is much more involved than Xlib itself. The device-dependent portions are 
in mit/server/ddx, and the device-independent portions are in mitserver/dix. The device-inde- 
pendent code should be your first stop, because it is here that protocol requests from Xlib 
arrive and are dispatched to the appropriate code. Search for the protocol request symbol 
you found in Xlib. It will appear in several source files. Start with the occurrence in dis- 
patch.c, and try to figure out what the code does. This will require following leads to other 
routines. 
If you do not find a routine in mit/server/dix, then it must be in the device-dependent code. 
mit/server/ddx has one directory in it for each brand of hardware to which a sample server 
has been ported. It also contains the directories/cfb,/mj'b,/mi, and/snf, which contain rou- 
tines used in writing the sample server device-dependent code. Note that servers may 
include code ostensibly for other machines. For example, the Sun sample server appears to 
use code in several of the directories for other servers such as dec and hp. 
Xlib and the X protocol are both defined by specification documents, not by any particular 
implementation. Never depend on the implementation details of the Xlib or server code. If 
you do, your code may not run on a machine that has optimized X software. This manual 
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documents only those features of Xlib and X in general that are governed by X Consortium 
standard specifications. If you follow the guidance you find in this volume and the details in 
Volume Two, Xlib Reference Manual, you will be in good shape. 
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!, (see modifiers) 
# directive, (see translations) 
#include files, 267 
* wiidcard, 262 
? wildcard, 26 l 
example, 273 
A 
accelerators, about, 51, 164, 203, 
221-226, 28 l 
adding, 222 
and translations; conflicts with, 
224; 
translation table limitations, 
223 
defining default table in code, 
226 
event propagation, 223 
for gadgets, 407 
for menus, 403, 407 
installing, 221; 
in multiple widgets, 225 
not usable in gadgets, 411 
accept_focus method, 429 
accepts_objects field, 418 
action hooks, 431 
actions, 114, 118, 389, 393,418, 
434 
about, 27, 30 
action proc format, 117 
adding to widget, 116 
contrasted with callbacks, 117 
defined in widget implementa- 
tion file, 160-161 
gadget parent example, 418 
in gadgets, 411 
naming conventions, 43 
using event data, 237 
vs. methods, 29 

Index 

widget instance pointer, 200 
widget/application conflicts, 
160 
(see also XtAddActions; Xt- 
AppAddActions; XtMenu- 
Popdown; XtMenuPopup.) 
actions table, adding, 116 
example, 115 
format, 115 
active grab, 387 
address mode, XtAddress con- 
stant, 290 
XtBaseOffset constant, 290 
Xtlmmediate constant, 290 
XtProcedureArg constant, 290 
XtResourceQuark constant, 290 
XtResourceString constant, 290 
XtWidgetBaseOffset constant, 
290 
AIt key, 212 
(see also modifiers.) 
anonymous tip, 35 
app-defaults, recommended bind- 
ings, 276 
app-defaults file, about, 33, 35 
directory, 38 
naming conventions, 33, 38 
Apple Computer, bitmap fonts, 
492 
font servers, 491 
Application class name, 36 
application contexts, 98 
about, 98,433-437 
applicationShellWidgetClass, 
300 
creating, 98 
multiple, 434-435 
XtOpenDisplay, 437 
application resources, about, 80 
adding, 80 
data structure, 81 
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application resources (cont'd) 
retrieving values, 85 
appres utility, 277 
arguments, Arg structure, 94 
argc, 91,302 
ARGSUSED lint comment, 43 
argument lists, 49; 
about, 94; 
creating, 49, 94-96; 
creating dynamically, 96; 
example, 95 
argv, 91,302 
command line, 90 
to actions, 123 
varargs, 93 
aspect ratio, 304 
Athena widgets, 64, 67, 70, 74, 
135-145,295,404 
about, i 8 
(see also Dialog widget; Form 
widget; MenuButton widget; 
Scroilbar widget; Text 
widget.) 
atoms, about, 320 
for protocols; 
WM_DELETE_WlNDOW, 311; 
WM_PROTOCOLS, 311; 
WM_SAVE_YOURSELF, 311; 
WM_TAKE_FOCUS, 311 
obtaining; example, 323 
predefined, 322 
standard, 331 
augmenting translations, 
120-121 
AVERAGE_WIDTH, 494 

B 
background, option (-back- 
ground,-bg), 87-88 
pixmap, 50 
processing, 246 
resources, 50 
window attribute, 170 
backing_store, window attribute, 
171,286 
binding, tight vs. loose, 260 
bit, bit gravity window attribute, 
171 
bitmap, about, 309 
files, 102 
fonts, 492 

546 

font-scaling algorithm, 492 
BitmapEdit widget, 64, 101-132, 
192, 347, 511 
about, 102 
BitmapEditClassRec, 152-153, 
245 
BitmapEditRec example, 
153-154 
class hierarchy of, 151 
instance part and record, 153 
Boolean values, 281 
border, border option (-border, 
-bd), 88 
bordercolor option (-border- 
color), 88 
borderwidth option (-bor- 
derwidth,-bw), 88 
pixmap, 50 
resources, 50 
width, 340 
window attribute, 170 
bounding box, 186 
Box widget, 71,222 
example, 60-61, 63, 65 
BulletinBoard widget, 464 
ButtonPress event, 211,390 
ButtonRelease event, 211,390 
buttons, 460 
C 

% C, 279 
caching, old size, 194 
resource, 288 
standard atoms, 331 
Xmu; initializing, 331 
callbacks, about, 26, 30, 40 
adding, 41-43; 
more than one, 80 
arguments to, 43, 79 
as resources, 40 
callback list, 79 
contrasted with actions, 117 
format, 43 
naming conventions, 43 
passing data, 77-79 
reasons, 27 
callbacks order of, 79 
Caption widget, 465 
Cardinal *, 507 
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debugging, 55 
DECnet, 312 
decoration, 31,309 
default, multiple click timing, 217 
size, 194 
delete child method, 341 
-- 
depth, 50, 183 
derived instances, 494 
of scalable fonts, 493-494 
destroy method, 169, 179, 
197-198 
about, 197 
Constraint, 365 
example from BitmapEdit, 198 
destructors, 288 
details in translations, (see trans- 
lations) 
dialog boxes, 408-409 
cascading, 409 
grabs in, 409 
without grabs, 409 
Dialog widget, 70, 74, 376 
popping up, 71 
directories, font, 486 
display, about, 6 
connecting to multiple displays, 
437 
depth, 484 
display_accelerator method, 
226 
lists, 185 
option (-display), 88 
DISPLAY environment variable, 
50 
distributed processing, 7 
DoesBackingStore Xlib macro, 
171 
DoesSaveUnders Xlib macro, 
171 
double clicks, 216-217 
downward chaining, 166 
drawing, about, 109-110, 154, 
165-167, 179, 185-188 
after Expose event, 168 
bitrnap cells, 175 
coordinate system, 4 
due to set_values method 
changes, 190 
in expose method, 180 
into Core widget, 107-108 
window attributes, 170-171 

DrawingArea widget, 477 
updating, 109 
-DXT_BC, 508 

E 
editres, 507 
use in programming, 439-447 
encapsulation, 29 
enter/leave compression, 250 
EnterNotify event, 210-211,250, 
389-390 
EnterWindow event, 230 
environment variables, DISPLAY, 
263 
LANG, 50 
syntax of, 264 
XAPPLRESDIR, 263 
XENVIRONMENT, 263 
XFILESEARCHPATH, 263 
XUSERFILESEARCHPATH, 263 
Error, Cannot convert .... 69 
error handling, 96, 423-426 
and application contexts, 426 
error resource database, 425 
levels, 424 
redefining handlers, 425 
string conversion warnings, 426 
XtApplnitialize, 92 
error messages, localization of, 
450 
event handlers, 30, 230-235 
about, 28,229 
adding, 230, 232-234 
for nonmaskable events, 
233-234 
raw, 235 
event sequences, 216 
events, about, 10, 205 
as argument of action, 117 
ButtonPress, 211,390 
ButtonRelease, 211,390 
EnterNotify, 210-211,250, 
389-390 
EnterWindow, 230 
event data; example of using in 
an action, 236 
event filters, 165, 187, 250 
event loop (see main loop) 
event masks; about, 230; 
window attribute, 171 
event queue, 249 

Index 549 



events (cont'd) 
event sequences, 220-221 
event structure, 235 
event-driven programming, 10 
Expose, 10, 24, 112, 123, 165, 
168, 245,250, 390 
Focusln, 210, 230, 429 
FocusOut, 210, 230, 429 
GraphicsExpose, 207,234 
in action routines, 123 
in gadgets, 410 
KeyPress, 211,429 
KeyRelease, 208, 211 
LeaveNotify, 210-21 l, 250, 
389-390 
list of types and structure 
names, 237-238 
mocking up from action, 186 
MotionNotify, 21 l, 217, 230, 
250, 390 
NoExpose, 207 
nonmaskable, 205,223, 
232-234; 
example of handlers, 205, 
223, 232 
propagation, 223 
selecting, 223 
SelectionClear, 312, 32 l 
SelectionNotify, 312, 322, 327 
SelectionRequest, 312-313, 
322-323 
translation table abbreviations, 
206-207 
using inside actions or event 
handlers, 235-236 
VisibilityNotify, 165, 207 
XEvent; example, 236 
exact color specification, 483 
expo.lcs.mit.edu, 35 
expose, Expose events, 24, 179, 
187, 390 
exposure, 10; 
compression, 187,250; 
(see also events, Expose.) 
method, 166, 179, 185, 
185-188,234; 
example from BitmapEdit, 
186; 
in gadgets, 410, 415-416 
extensions, about, 12 
structures, 418, 437 

fallback resources, 271 
files, character limit in filenames, 
150 
file input, 239-241; 
source masks, 239 
finding, 264 
including in resource files, 267 
paths to resource, 264 
resource, 433 
using names in resources, 281 
float type, setting resources, 46 
floating point numbers, 281 
FocusIn event, 210, 230 
FocusOut event, 210, 230 
font clients, 491 
font names, overspecified, 495 
scalable fields, 494 
underspecified, 495 
well-formed, 493 
font scaling, 492 
font scaling algorithms, 492 
font service, 490-498 
architecture, 491 
configuration, 491 
diagram, 491 
motivation for, 490 
new features, 491 
protocol, 490 
scaling, 492 
used for licensing, 491 
font set, 449 
-font option, lack of, 450 
fonts, bitmap, 492 
directories, 486 
display (xfd), 486 
families, 486, 489 
font conventions; boldface, vi; 
italics, vi; 
typewriter font, vi 
font option (-font), 87-88 
hand-tuned, 493 
naming convention, 487 
outline, 492, 493 
printer, 486 
scalable, 492-493; 
(see also scalable fonts.) 
scaling, 493 
screen, 486 
specifying, 481 
specifying as resources, 281 
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fonts (cont'd) 
wildcarding, 489 
foreground, option (-foreground, 
-fg), 88 
Form widget, 103,359-375,474 
about, 67-70, 464, 474 
example, 474 
layout method, 364 
Frame widget, 344 
ftp, 35 
function prototype, XtCreatePo- 
pupChildProc, 408 
G 
gadgets, about, 62, 169, 381, 
410-419 
accelerators, 407; 
not usable, 411 
actions in, 411 
class hierarchy, 411-412 
class structure, 413 
composite parent, 410, 415-419 
Core class structure, 412 
drawbacks of, 410 
event handling in, 410 
expose method, 415 
implementation file, 414 
instance structure, 414 
internals, 412-415 
private header file, 413-414 
public header file, 415 
query_geometry method, 415 
reason for, 410 
set_values_almost method, 415 
Sme, 404-415 
SmeBSB, 404-415 
SmeLine, 404-415 
superclass, 414 
unused Core fields in, 414-415 
games, 242 
GCs, (see graphics contexts) 
geometry management, 63-64, 
303, 341,344-345,347,357, 
359 
about, 34, 191,194-197, 
339-377 
almost right, 357 
border width, 340 
changing, 343 
composite resource, 359 
compound widgets, 376 

constraints, 359, 364 
delaying recalculation, 375 
height, 343 
initial geometry negotiation, 
342, 344 
inserting children, 358 
minimal useful size, 351 
querying; preferred geometry, 
354; 
XtQueryOnly constant, 356 
resizing, 339, 344; 
by application, 346-347; 
by user, 344-345; 
by widget request, 345-346 
scope, 340 
size preferences, 354 
stacking order, 340, 376 
trickle-down, 354 
unmanaging widget, 353 
what if requests, 356 
width, 343 
XtGeometryAlmost, 356 
XtGeometryDone, 356 
XtGeometryNo, 356 
XtGeometryResult, 356 
XtGeometryYes, 356 
XtMakeGeometryRequest, 345, 
347 
XtMakeResizeRequest, 357 
XtQueryGeometry, 344, 346 
XtWidgetGeornetry, 356 
(see also methods; methods, 
set_values_almost; XtDes- 
troyWidget.) 
geometry option, (-geometry), 88 
get_values_hook method, 169, 
295 
global variables, 71, 74, 77 
grabs, about, 387 
active vs. passive, 387 
adding or removing explicitly, 
409 
exclusive vs. nonexclusive, 
388, 401 
global, 388 
grab modes, 401 
in dialog boxes, 409 
keyboard, 387 
passive, 388 
pointer, 387 
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grabs (cont'd) 
reasons for in menus, 389 
graphics contexts, about, 109, 
154, 171 
caching, 180, 183 
changing, 183, 190-191 
creating, 180, 183, 185 
exclusive or logical function, 
319 
freeing, 190, 197 
hardcoding values in, 185 
read-only, 183 
reasons for, 109 
setting with resources, 185 
sharing between instances, 180 
GraphicsExpose event, 234 
H 
hand-tuned fonts, 493 
hardcoding, resources, 39, 92, 
94-95 
translations, 121 
header files, 30, 46, 50, 150, 240, 
411,504 
not included twice, 153 
height, 343 
checking in initialize method, 
181 
hints, about, 300-311 
icon position, 303 
position, 53 
size, 303-304 
size increment, 304 
hooks, 431 
Hyper key, 212 
(see also modifiers.) 
I 
ICCCM, 11,299, 320, 323, 
329-333 
icon, creating pixmap, 308-309 
iconic option, (-iconic), 88 
popups, 302 
setting; name, 308; 
pixmap, 299, 308 
size and position, 499 
starting application as, 303 
ifndef statement, 153 
Imakefile, writing, 265 

implementation file, (see widget) 
include files, 30, 46, 50, 150, 153 
in widget implementation, 156 
#include files, 267 
incremental selections, 333 
inheritance, about, 20, 44, 51, 
163-172 
adding features to superclass, 
172 
among Motif Widgets, 21 
among OPEN LOOK widgets, 
461 
in widget class and instance 
record, 151-152 
of chained methods, 166 
of conflicting methods, 172 
of Core resources, 49, 51 
of self-contained methods, 166 
of superclass method, 169 
resources, 157, 159-160 
styles, 166-167 
using Xtlnherit constants, 166 
widget not using resource 
value, 53 
initial size, 343 
initialize method, 179, 181-185, 
323,349 
about, 181 
Constraint, 365 
creating GCs in, 183 
example from BiunapEdit, 182 
initialize hook method, 295 
input, from file, 239-241 
from pipe, 241-242 
InputOutput window, 167 
source masks, 239 
input methods, and text interna- 
tionalization, 451 
insert child method, 341 
instance, about, 20 
names, requirements for, 33 
record, 151; 
adding variables to, 154; 
allocating storage, 155; 
BiunapEdit widget, 153-154; 
contents, 151 
structures, 151-176, 181; 
constraints in, 362 
Inter-Client Communication 
Conventions Manual, (see 
ICCCM) 
internationalization, 447 
Intrinsics, 156 

552 X Toolkit Intrinsics Programming Manual 



about, 9 
Intrinsic.h header file, 30 
IntrinsicP.h header file, 156 
K 

key events, (see events or transla- 
tions) 
keyboard, keyboard focus, 305; 
about, 305,429; 
setting, 305; 
styles, 305; 
(see also XtNinput.) 
shortcuts; (see accelerators) 
keycodes, about, 208,429 
KeyPress event, 211 
KeyRelease event, 211 
keysyms, about, 208,429 
converting case, 215 
key generated, 213 
keysymdef.h header file, 209, 
212 
naming conventions, 209 
L 
%L, 279 
Label widget, 22, 28, 71,106, 
192, 341,390, 504 
Label.h file, 30 
labels, setting, 45 
LANG environment variable, 
263, 268 
language, portability, 44 
language procedures, registering, 
448 
language strings, 450 
layout Form method, 364 
LeaveNotify event, 210-211,250, 
389-390 
LeaveWindow event, 230, 398, 
402 
libraries, Xaw, 35 
Xext, 12 
Xlib, 35 
Xt, 35 
lint, 43, 94 
List widget, 135,230, 471 
loading, scalable fonts, 496 

locale, dependencies in X Toolkit, 
448 
establishing; in X Toolkit, 448 
localization, of error messages, 
450 
loose bindings, 260 

M 
macros, 427-428 
main loop, 31, 34 
customizing example, 249 
internals, 249 
MainWindow widget, 344 
Makefile, writing, 265 
mapping, 207 
about, 51 
mechanism without policy, 9,299 
memory allocation, 431 
for widget instance record, 164 
menus, about, 34, 381-419, 464 
accelerators in, 403,407 
cascaded, 383, 399-403 
operation of, 385 
panes, 62 
panes in, 385 
pointer grabbing, 387,389 
popping down, 387, 395,403 
popping up, 393, 396 
pulldown, 383, 395-397; 
example, 396-397 
SimpleMenu widget, example, 
404, 406 
spring-loaded, 383, 387 
XtMenuPopdown, 389 
XtMenuPopup, 389 
messages, about, 29 
OOP vs. Xt, 29 
Meta key, 212 
methods, about, 167-169 
accept_focus, 168, 429 
and instance structure, 151 
change_managed, 341-342, 
353, 374; 
in constraint widgets, 374 
class_initialize, 168, 287,418 
class_part_initialize, 168 
Constraint; destroy, 365; 
initialize, 365-366; 
resizing, 371 
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methods (cont'd) 
declarations in widget imple- 
mentation file, 162 
delete_child, 341,358-359 
destroy, 169, 179, 197-198, 
365; 
example, 197-198 
display_accelerator, 226 
drawing; due to changes in 
set_values, 190; 
in expose, 180 
expose, 29, 168, 179-180, 
185-188, 234, 410, 415-416 
Form layout, 364 
gadget; expose, 415; 
query_geometry, 415; 
set_values_almost, 415 
geometry_manager, 341,345, 
355-357, 367 
get_values_hook, 169, 295; 
example, 295-296 
in OOP, 29 
inheritance; adding to super- 
class, 172; 
of superclass, 169 
initialize, 167, 179-185,365; 
calling XlntemAtom, 
179-185,349; 
example, 181-182; 
in constraint widget, 365 
initialize_hook, 167,295 
insert_child, 341 
insert_position, 358-359 
not known to Xt, 364 
query_geometry, 169, 179, 
194-197,341,356; 
about, 179, 194-197,341; 
in constraint widget, 
350-351,375; 
in gadgets, 374, 415 
realize, 168,304, 344, 349 
reconciliation, 172 
resize, 168, 179, 191-194, 341, 
343, 371; 
in composite widget, 350; 
in constraint widget, 
372-373; 
in gadget parent, 417 
resources and set_values, 
189-191 
set_values, 168, 179-180, 
189-191,345,347, 349-350, 
373 

set_values_almost, 168,347, 
357-358; 
in gadgets, 415 
set_values_hook, 168,295-296 
vs. actions, 29 
minimal useful size, 351 
Mod keys, 212 
(see also modifiers.) 
modal cascade, 384 
modal popups, 384 
modifiers, !, 215 
adding, 213 
and event sequences, 218 
case-specifics, 215 
colon, 215-216 
displaying list, 213 
for button events, 218 
keys, 211-216 
matching exactly, 215 
negating, 214 
None, 215 
mono vs. color, 433 
Motif, 385 
application's look and feel, 470 
pop-up widgets, 476 
Motif widgets, 35, 64, 469-477 
about, 19 
command, 470 
composite, 472-476 
DrawingArea, 477 
inheritance among, 21 
Text, 477 
(see also Command widget; 
Label widget.) 
motion compression, 250 
MotionNotify event, 211,230, 
250, 390 
multiple, click timing, 217 
top-level shells, 436 
mwm, keyboard focus in, 306 
use of input hint, 305 
N 
%N, 279 
name option (-name), 88 
naming conventions, for widgets, 
503 
native language option, 448 
netnews, 539 
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networked font service, (see font 
service) 
newlines, in translations, 204 
nonfatal error, 207 
(see also error handling.) 
notify method, 418 
notify modes, (see translations) 

objects, about, 28 
Object class, 412 
object-oriented programming, 
ii, 28-29, 234 
OLIT widget set, 455 
OOP, (see objects, object-oriented 
programming) 
OPEN LOOK, application's look 
and feel, 459 
pop-up widgets, 466 
widgets 
command, 460-462 
text, 468 
optimization, 123, 194, 435 
options, abbreviating, 87 
argument styles, 90 
-background, 87-88, 481 
-border, 88, 481 
-bordercolor, 88 
-borderwidth, 88 
command line; styles, 90 
command-line, 86 
custom, 262 
defining your own, 88 
-display, 88 
-font, 88 
-foreground, 88, 481 
-geometry, 304, 498-499 
handling errors in, 92 
-iconic, 88,303 
options table example, 90 
options table; xbitmap, 105 
overriding standard, 91 
-rv/+rv, 88 
-selectionTimeout, 88 
standard, 87 
-synchronous, 88 
-title, 88 
-xrm, 87, 262 
order of, callbacks, 79 
outline fonts, 492-493 
OverrideShell, over- 

rideShellWidgetClass, 74 
OverrideShell widget, 302 
overriding, redirect, 302; 
window attribute, 171 
standard options, 91 
translations, 120-121 
overspecified font names, 495 

Paned widget, about, 66 
Panner widget, 136 
parsing, command-line arguments, 
88-92 
translations, 121 
part (vs. record), 152 
passive grab, 388 
path resources, 264 
paths, to resource files, 264 
pipe input, 241-242 
pixel values, about, 110 
PIXEL_SIZE, 494 
pixmap, about, 50, 186 
freeing, 197 
updating in widget, 106 
pointer, 387 
about, 4 
events (see events or transla- 
tions) 
(see also grabs.) 
POINT_SIZE, 494 
pop-up menus, example, 390, 393 
pop-up widgets, 457 
Motif, 476 
OPEN LOOK, 466 
popups, about, 17, 70 
cascading, 381 
creating; in work procedure, 
247 
creating just before popping up, 
76 
from callback function, 75 
linking group, 302 
menus, 381 
menus, spring-loaded using 
Box widget, 390, 393-394 
modal, 384 
modeless, 384 
moving to desired position, 75 
OverrideShell, 302 
sensitivity, 409 
spring-loaded, 384 
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popups (cont'd) 
using, 70-72, 74 
when application is iconified, 
302 
portability, 95,239, 430, 433-434 
position, about, 53,282 
hints, 303 
relative to root window, 309 
setting with resources, 53 
PRIMARY selection, 313 
printer fonts, (see fonts) 
private header file, BitmapEdiP.h, 
151-155 
private instance variables, 154 
program structure, 30 
properties, about, 312 
and atoms, 320 
property, RESOURCE_MANAGER, 
262-263 
SCREEN_RESOURCES, 263 
protocol, network, 5 
WM_DELETE_WINDOW atom, 
311 
WM_PROTOCOLS atom, 31 l 
WM_SAVE_YOURSELF atom, 
311 
WM_TAKE_FOCUS atom, 31 l 
Protocols.h header file, 310 
public, functions, 173 
header file, 30, 415; 
BitmapEdit.h, 150, 172-174 
instance variables (see 
resources) 
routines, 375 
public functions, about, 103 
reasons to use, 105 
pulldown menu, 383, 395 
example, 397 
vs. spring-loaded, 383 
push buttons, 15 
Q 
quarks, 293 
query_geometry method, 169, 
194-197,415 
about, 194 
example from BitmapEdit, 197 
gadgets, 374-375,415 
querying, scalable fonts, 496 

R 
R5, new features;font service, 491 
raw event handlers, 235 
(see also events.) 
realization, 34, 186, 190 
realize method, 166, 169, 171, 
304, 349 
reason, in callbacks, 27 
RectObj, 170, 411-412, 414 
redrawing windows, 24, 185 
regions, 187, 417 
registering, actions (see actions) 
converters, 285-291 
event handlers, 232-234 
fatal error handlers, 168, 
423-426 
nonfatal error handlers, 423-426 
registering language procedures, 
448 
Release 4 (R4), 210, 382, 437 
reparenting, 309, 398 
Repeater widget, 136 
representation types, 81, 83 
about, 255, 257 
requirements for, instance names, 
33 
resizing, 341 
about, 63, 179, 191-194, 339, 
344 
caching old size, 194 
reasons, 357 
resize method, 179, 191-194, 
341; 
example from BitmapEdit, 
193; 
in gadgets, 417 
(see also methods, resize.) 
RESOLUTION_X, 494 
RESOLUTION_Y, 494 
resource databases, ? wildcard, 
261 
screen specific, 269 
X Toolkit, 262 
resource files, color vs. mono, 433 
customized, 278 
including files in, 267 
merging, 262 
paths to, 264 
syntax, 260-262 
resource strings, screen specific, 
269 
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RESOURCE_MANAGER prop- 
erty, 262-263,269 
resources, about, 23, 33, 35, 44, 
49, 51,255-259 
and set_values method, 
189-191 
and specifying locales, 448 
application, 80 
caching, 288 
callbacks, 40 
checking validity, 181 
classes and instances, 83 
comment character in files, 261 
constraint, 67, 359 
customization, 264 
database; sources, 262 
default address; interpreting, 
259 
default value; converting, 283; 
retrieving, 285; 
setting, 84, 284 
defined; by Core, 49; 
characteristics, 83-84; 
in widget, 157, 159-160 
fallback, 271 
Form widget, 67, 359, 361 
format of definitions, 260-262 
freeing compound strings, 48 
hardcoding; advantages, 39, 
92, 94; 
disadvantages, 93 
in instance record, 154 
inheritance of, 44, 157, 159-160 
interactions between, 51-52, 54; 
example, 52 
loading; from .Xdefaults file, 
52; 
with xrdb, 52 
loose bindings, 260 
merging of files and sources, 
262-265 
naming, 83,256 
precedence rules, 274-277 
representation types, 81, 83, 
257 
resource conversion; about, 83; 
in Xmu, 282; 
registering, 287 
resource list; declaring, 256; 
example, 82-83; 
format, 83-84; 
XtR, 81 

retrieving; application 
resources, 85-86 
server resources, 24 
setting; about, 24 
setting floats, 46 
setting; for multiple widgets, 
62; 
for widget hierarchy, 62; 
in application, 44 
setting in application, 92 
setting; with XtSetValues, 47; 
XtNinput, 306 
size, 258 
sources priority, 264 
specifications; about, 274-277; 
errors in, 38; 
format, 36, 39; 
wildcards in, 260 
specifying translation tables as, 
279 
symbolic constants, 38, 46 
tight bindings, 260 
type conversion, 38, 280-294 
types table, 257 
use of classes, 257 
values; changing, 189; 
getting, 44, 49, 259-277 
XmNdestroyCaliback (Core), 
40 
xnlLanguage, 262, 268 
XtN constants, 173 
XtNaccelerators (Core), 50 
XtNallowShellResize (Shell), 
302 
XtNancestorSensitive (Core), 
50 
XtNargc (Shell), 301-302 
XtNargv (Shell), 301-302 
XtNbackground (Core), 50 
XtNbackgroundPixmap (Core), 
50 
XtNbaseHeight (Shell), 302, 
304 
XtNbaseWidth (Shell), 302, 304 
XtNborderColor (Core), 50 
XtNborderPixmap (Core), 50 
XtNborderWidth (Core), 50 
XtNcolormap (Core), 50 
XtNdefaultDistance (Form), 
360 
XtNdepth (Core), 50 
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resources (cont'd) 
XtNdestroyCallback (Core), 50 
XtNgeometry (Shell), 301, 
303-304 
XtNheight (Core), 50 
XtNheightInc (Shell), 302, 304 
XtNhorizDistance (Constraint), 
360 
XtNiconic (Shell), 301,303 
XtNiconMask (Shell), 302 
XtNiconName (Shell), 302, 308 
XtNiconPixmap (Shell), 302, 
308 
XtNiconWindow (Shell), 302 
XtNiconX (Shell), 301,303 
XtNiconY (Shell), 301,303 
XtNinitialState (Shell), 302 
XtNinput (Shell), 305-306 
XtNinsertPosition (Composite), 
359 
XtNmappedWhenManaged 
(Core), 50, 353 
XtNmaxAspectX (Shell), 302, 
304 
XtNmaxAspectY (Shell), 302, 
304 
XtNmaxHeight (Shell), 302, 
304 
XtNmaxWidth (Shell), 302, 304 
XtNminAspectX (Shell), 302, 
304 
XtNminAspectY (Shell), 302, 
304 
XtNminHeight (Shell), 302, 304 
XtNminWidth (Shell), 302, 304 
XtNoverrideRedirect (Shell), 
301-302 
XtNpixmap (Core), 106 
XtNpopdownCallback (Shell), 
396 
XtNpopupCallback (Shell), 
396-397 
XtNsaveUnder (Shell), 302 
XtNscreen (Core), 50 
XtNsensitive (Core), 50 
XtNtitle (Shell), 301,308 
XtNtransient (Shell), 301-302 
XtNtranslations (Core), 50, 118, 
121 
XtNvertDistance (Constraint), 
360 

XtNwaitForWm (Shell), 
301-302 
XtNwidth (Core), 50 
XtNwidthlnc (Shell), 302, 304 
XtNwindowGroup (Shell), 
301-302 
XtNwmTimeout (Shell), 
301-302 
XtNx (Core), 50 
XtNy (Core), 50 
reverse option (-rv/+rv), 88 
RGB color model, 483-484 
root window, 50, 75, 305,309, 
393 
root_geometry_manager, 357 
round trip request, 31 
rubber-band outline, 191, 319 
S 
%S, 279 
save under window attribute, 
-- 
171 
scalable fields, 494 
scalable fonts, 490-498,492 
and scalable fields, 494 
average width, 494-495 
backwards compatibility, 493 
derived instances, 493-494 
finding, 493,496 
in complex applications, 496 
in simple applications, 496 
loading, 496 
naming, 493 
overspecified names, 495 
pixel size, 494 
point size, 494 
querying, 496 
recognizing, 496 
resolution, 494 
scaling, 496 
underspecified names, 495 
well-formed names, 493 
scaling fonts, 493 
screen, 4 
about, 6 
example of typical X Window, 
5 
fonts; (see fonts) 
layout of, 303 
monochrome, 183 
setting defaults for, 270 

558 X Toolkit Intrinsics Programming Manual 



screen (cont'd) 
specifying default, 436 
SCREEN_RESOURCES property, 
263,269 
scrollbars, about, 15,465,475 
Scrollbar widget, 15, 64, 286 
ScrollBox widget, 347-354 
Viewport widget, 65,376 
selections, 208, 312 
about, 299, 311-336 
and CurrentTime, 321 
asserting ownership, 320-321 
CLIPBOARD, 336 
converting; example, 325-326, 
332-333; 
selection, 324-326; 
standard selections, 331-333 
disowning, 335 
handling large selections, 333 
highlighting, 315, 319-320; 
example, 315, 319-320 
incremental, 333 
losing selection, 32 l, 329 
pasting, 324; 
example, 327-328; 
selection, 327-328 
querying for desired target, 
330-333 
requesting, 321-322 
target types, 322-324 
timeout, 335 
XA_CLIPBOARD, 320, 336 
XA_MULTIPLE, 333 
XA_PRIMARY, 313, 320 
XA_SECONDARY, 320 
XA_TARGETS, 323, 330 
(see also events, SelectionRe- 
quest; SelectionClear event; 
SelectionNotify event; Selec- 
tionRequest event.) 
self-contained methods, (see 
inheritance) 
sensitivity, 5 l, 75, 94, 251 
in popup callbacks, 409 
sequences, event, 216 
server, about, 5-6 
freeing server resources, 197 
servers, guide to server code, 542 
setting resources in application, 
45 
set values method, 168, 179-180, 
189-191,349-350 
about, 189 

example from BimaapEdit, 189 
set values almost method, 415 
in gadgets, 168 
set values hook method, 168, 
295-296 
sharing GCs, 180 
Shell widget, 17, 22, 59, 103 
about, 17, 33, 53, 59, 64, 299 
reason for invisibility, 61 
resources, 301-306, 308-309 
Simple widgets, 456 
SimpleMenu widget, 385, 
404-408, 415-419 
single-line input field, 311 
sink, in Athena Text widget, 295 
size, 339 
hints, 303-304 
preferences, 354 
sizeof, 164 
Sme, 404-415 
software architecture, 8 
source, compatibility, 437 
files for widget, 150 
in Athena Text widget. 295 
obtaining source code, 35 
spring-loaded menu. 387-395 
vs. pull-down, 383 
stacking order, 340, 376 
standard colormaps, Xmu utili- 
ties. 307 
stdio.h file. 156 
string constants. X Toolkit. 507 
string encodings, in the X Toolkit. 
448 
strings, setting, 45 
string to bitmap converter, 286 
StringDefs.h header file, 30, 46, 
83, 156, 285 
StringToWidget resource con- 
verter, 360 
StringToWidget resource con- 
verter. 68 
StripChart widget, 137 
structure, of Athena applications, 
30 
subclass, 22 
subclassing, 149 
submenus, 401 
cascading, 403 
creating, 400 
popping up, 400 
(see also XtPopup.) 
subparts, 164, 169, 294-296 
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subresources, 164, 169, 294-296 
managing, 296 
Super key, 212 
(see also modifiers.) 
superclass, 1 64, 190 
about, 21 
class structure, 152 
gadget, 414 
inheritance, 51 
of Core, 411 
synchronous option, 88 
syntax functions, 92 

%T, 279 
TCP/IP, 312 
Text widget, 74, 140-141,165, 
311 
Motif, 477 
OPEN LOOK text widgets, 468 
tight bindings, 260 
tilde, 214 
tiling, 50 
timeouts, about, 242 
adding, 242 
and visibility interest, 245 
example, 243-244 
removing, 244-245 
timing, multiple clicks, 217 
title option (-title), 88 
Toggle widget, 138 
top-level, 
topLevelShellWidgetClass, 
301 
widget, 33 
(see also Shell widget.) 
training available for Xlib, 539 
transientShellWidgetClass, 70, 
74, 300 
translation tables, encoding, 448 
specifying as resources, 279 
translations, 118-121,223 
! modifier symbol, 215 
about, 27, 51 116, 118 
#augment directive, 120 
augmenting, 120-121 
compiling; when widget class 
initialized, 161 
defining; default in Core class 
part, 165; 
in source, 121 

details in, 208-211 
differences between directives, 
205 
double-clicks, 216 
event abbreviations, 206-207 
event sequences, 216-219 
hardcoding, 121 
in widget implementation file, 
160-161 
inheritance, 160 
interactions between, 219-223 
keyboard events, 208-209 
merging, 220 
modifiers, 211-216, 213; 
and event sequences, 218 
modifier symbol, 215-216 
Motion events, 217 
newlines in, 204 
*Notify details, 210 
order, 219-220 
#override directive, 120 
overriding, 120-121 
parsing, 121 
#replace directive, 120 
replacing, 120-121 
resource converters, 282 
syntax, 204 
tilde modifier symbol, 214 
translation table; example, 118 
(see also accelerators.) 
type converters, 38 
about, 96 
explicitly invoking, 291-292; 
example, 291-292 
format, 292-294 
passing arguments to, 289; 
example, 289 
registering, 285-291 
(see also resources.) 
typedefs, 155 

underspecified font names, 495 
unmanaging widget, 353 
upward chaining, 166 
Usenet network news, see net- 
news, 539 
uunet, 35 
uwm, 382 

560 X Toolkit Intrinsics Programming Manual 



V 
varargs interfaces, advantages 
and disadvantages, 97 
VendorSheli widget, 305 
Viewport widget, 347 
virtual colormaps, 171,306 
visibility interest, 165,245-246 
W 
Warning, Cannot convert .... 69 
warnings, 423 
(see also error handling.) 
well-formed font names, 493 
widget set, OUT, 455 
widgets, 59 
about, 9, 15, 19 
actions example, 198, 200 
adding to parent list, 16 
as data types, 34 
child widget; creating/manag- 
ing, 59, 341; 
layout of, 351-352 
converting (R4 to RS), 507 
creating, 30, 80 
declaring class record pointer, 
169 
default size, 194 
defining conventions, 150, 260; 
summary, 176 
destroying, 27, 197-198 
Exclusives and Nonexclusives, 
462 
framework of code, 149-176 
getting data, 103; 
hierarchy; creating, 61 
implementation file; actions 
table, 160-161; 
declaration of methods, 162; 
resources, 157, 159-160; 
translation table, 160-161 
implementation files, 150, 
155-172 
include files, 150 
inheritance among (Motif), 21 
instance structure, 181 
internals, 149-176 
macros for, 427 
management, 59, 194-197; 
child, 181-185 
mapping, 51; 

windows, 34 
moving/resizing, 50 
name def'med, 164 
naming conventions, 503 
popping up, 75-76 
private header file, 150-155 
public header file, 150, 172-174 
realizing, 190 
record size, 164 
removing, 16 
resizing, 64, 191-194, 341-349; 
by application, 346; 
by parent, 345 
reasons for, 357 
sets; about, 9, 18; 
compared, 456; 
Motif, 18, 469-477; 
OPEN LOOK, 18, 459-469; 
special defaults, 305 
source file, 150 
superclass; inheritance, 51 
techniques for writing, 174 
windowless (see gadgets) 
(see also individual widgets 
alphabetically.) 
width, 343 
checking in initialize method, 
181 
wildcards, and resource compo- 
nent names, 261 
in font names, 489 
in resource specifications, 38, 
260 
in scalable fonts, 493 
window, geometry, 498 
unnamed class, 412 
WindowObj class, 170 
window attributes, 172 
about, 170 
background, 170 
backing_store, 171,286 
bit_gravity, 171 
border, 170 
colormap, 171,308 
cursor, 171 
event_mask, 171 
override_redirect, 171 
save_under, 171 
setting in realize method, 
171-172 
window manager, 63-64, 
299-311,339 
about, 11, 31 
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window manager (cont'd) 
and decoration, 309 
and icons, 308-309 
click-to-type, 305 
colormaps, 306-307 
focusing styles, 210 
hints, 1 l, 300-311 
input models, 305 
interacting with, 300-311 
keyboard focus, 305-306 
pointer focus, 305 
real estate driven, 305 
reparenting, 309, 398 
screen layout, 303-304 
WM_DELETE_WINDOW, 311 
WM_PROTOCOLS, 311 
WM_SAVE_YOURSELF, 311 
WM_TAKE_FOCUS, 311 
work procedures, registering, 
246-248 
removing, 247 
X 
X, about, 3 
extensions to, 12 
source software, 535 
X Protocol, 5, 312 
XView, 9 
X Consortium, address, 540 
current members, 540-542 
X Font Service Protocol, 490, 
492 
X Logical Font Description 
(XLFD), 492-493 
X Portable Character Set, 262 
X Toolkit, and internationalization, 
447 
and locale dependencies, 448 
and string encoding, 448 
building resource databases, 
262 
changes in X 11RS, 507 
locale, establishing, 448 
string constants, 507 
Xll/intrinsic.h, 508 
XllRS, X Toolkit changes, 507 
Xl l/Xos.h, 508 
XA_CLIPBOARD atom, 320 
XA_MULTIPLE property, 333 

XAPPLRESDIR environment 
variable, 263 
XA PRIMARY atom, 313,320 
XA SECONDARY atom, 320 
-- 
XA TARGETS atom, 323 
Xatom.h file, 320, 322 
Xaw library, 35 
xbitmap application, 102, 511 
xbitmapl; example, 103-106 
xbitmap2 exanple, 106 
xbitmap3 example, 106 
xbitmap4 example, 122-132 
XChangeGC Xlib function, 183 
XClearArea Xlib function, 190 
xclipboard, 332, 336 
XConfigureWindow Xlib func- 
tion, 377 
XCopyArea Xlib function, 112, 
188,207 
XCopyColormapAndFree Xlib 
function, 307 
XCopyPlane Xlib function, 112, 
188,207 
XCreateGC Xlib function, 109, 
180 
XCreateWindow Xlib function, 
172 
XDefaultFontSet, 449 
.Xdefauits file, 52, 262 
.Xdefaults-hostname file, 263 
xedit, 31 l 
XENVIRONMENT environment 
variable, 263 
xev, 213 
xfd (font displayer), 489 
XFILESEARCHPATH, 265-266, 
279 
XFILESEARCHPATH environ- 
ment variable, 263 
XFiush Xiib function, 435 
XFontSet, 449, 492 
XGCValues structure, 183 
XGetlconSizes Xlib function, 309 
XGetStandardColormap Xlib 
function, 307 
xgoodbye.c example, 41 
xhello.c example, 31-32 
XInternAtom Xlib function, 
322-323 
XLFD, 492-493 
Xlib, training available, 539 
Xlib library, 35, 185, 187, 191 
XListFonts, 492 
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and scalable fonts, 493 
new semantics, 493 
xioad, 305 
XLoadFont, 492 
XLoadQueryFont, 492 
XLookupString Xlib function, 
430 
XLowerWindow Xlib function, 
377 
xmh, 66, 311 
Xm.h header file, 156 
xmodmap, 213 
XmP.h header file, 156 
Xmu library, 288, 331 
atom caching; initializing, 331 
resource converters in, 282 
XmuConvertStandardSelection, 
331-333 
XmulntemAtom, 331 
XNextEvent Xlib function, 344 
-xnlLanguage option, 448 
XnlLanguage, 448 
xniLanguage, 262, 268, 448, 450 
-xnlLanguage command line 
option, 262 
XParseGeometry Xlib function, 
304 
XRaiseWindow Xlib function, 
377 
xrdb client, 52, 259, 263 
XRectInRegion Xlib function, 
187 
XResourceManagerString, 269 
XRestackWindows Xlib func- 
tion, 377 
Xrm, XrmOptionDescRec; 
example, 90; 
structure, 88 
XrmoptionIsArg argument 
style, 90 
XrmOptionKind enum values, 
XrmoptionNoArg argument 
style, 90 
XrmoptionResArg argument 
style, 91 
XrmoptionSepArg argument 
style, 91 
XrmoptionSkipArg argument 
style, 91 
XrmoptionSkipLine argument 
style, 91 

XrmoptionSkipNArgs argument 
style, 91 
XrmoptionStickyArg argument 
style, 90 
XrmCombineFileDalabase, 267 
XrmGetFileDalabase, 267 
XrmLocaleOfDalabase function, 
263 
-xrm option, 450 
XSelectlnput Xlib function, 223, 
230 
XSetErrorHandler Xlib func- 
tion, 423 
XSetInputFocus Xlib function. 
429 
XSetIOErrorHandler Xlib func- 
tion, 423 
xstuff server, 536-538 
XSync Xiib function, 435 
Xt library, 35 
XtActionProc, 117 
XtAddActions, 418 
XtAddCallback, 42-43, 282 
arguments, 43 
XtAddCallbacks, 80 
XtAddConverter. 287 
XtAddEventHandler. 229-230 
arguments, 232 
when to call, 232 
XtAddGrab, 409 
XtAddlnput, 434 
XtAddRawEventHandler, 235 
XtAddress address mode con- 
slant, 290 
XtAddressMode enum, 290 
XtAIIocateGC, 180 
XtAppAddActionHook, 431,434 
XtAppAddActions, 114, 118, 160, 
434 
XtAppAddConverter, 434 
XtAppAddInput, 239, 241,434 
XtAppAddTimeOut, 242 
XtAppAddWorkProc, 246 
XtAppCreateSheli, 300, 434, 436 
XtAppError, 424-425,434 
XtAppErrorMsg, 424-425,434 
XtAppGetErrorDatabase, 434 
XtAppGetErrorDatabaseText, 
434 
XtAppGetSelectionTimeout, 434 
XtAppInitialize, 30, 87, 185,259, 
262, 434, 507 
fallback resources in, 271 
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XtGeometryAImost constant, 
196, 344, 351,370, 375 
XtGeometryDone, 356 
XtGeometryDone constant, 355, 
367 
XtGeometryNo, 356 
XtGeometryNo constant, 196, 
358, 368, 375 
XtGeometryResult, 356 
XtGeometryResult enum, 196, 
350, 354, 368, 370, 375 
XtGeometryYes, 356 
XtGeometryYes constant, 196, 
351,354, 367-368, 370, 375 
XtGetActionKeysym, 431 
XtGetApplicationNameAnd- 
Class, 428 
XtGetApplicationResources, 80, 
259 
XtGetConstraintResourceList, 
363 
XtGetErrorDatabase, 426, 434 
XtGetErrorDatabaseText, 426, 
434 
XtGetGC, 109, 180, 183, 190 
when not to use, 183 
XtGetKeysymTable, 431 
XtGetResourceList, 160, 277 
XtGetSelectionRequest, 333 
XtGetSelectionTimeout, 335,434 
XtGetSelectionValueIncremen- 
tal, 334 
XtGetSelectionValues, 313, 
321-323, 330, 335 
XtGetSubresources, 296 
XtGetSubvalues, 296 
XtGetValues, 24, 49, 75, 398 
XtGrabButton, 389, 432 
XtGrabKey, 389, 432 
XtGrabKeyboard, 432 
XtGrabNone grab mode, 409 
XtGrabPointer, 387,432 
XtHasCalibacks, 428 
XtIMAIternateInput constant, 
250 
XtImmediate address mode con- 
stant, 290 
XtIMTimer constant, 250 
XtIMXEvent constant, 250 
XtInherit constants, 166 
XtInheritDeleteChild, 359 

XtInheritGeometryManager, 
355 
XtInheritInsertChild, 359 
XtInheritRealize, 170 
XtInheritSetValuesAlmost, 358 
XtInitialize, 507 
XtInsertEventHandler, 232 
arguments, 232 
when to call, 232 
XtlnstallAccelerators, 221-222 
XtInstallAllAccelerators, 
221-222, 225 
XtInternAtom Xlib function, 320 
XtIsComposite, 427 
XtIsManaged, 427-428 
XtIsRealized, 186, 427-428 
XtIsSensitive, 428 
XtIsSubclass, 427 
XtKeyProc, function prototype, 
430 
XtKeysymToKeycodeList, 431 
XtLoseSelectionIncrProc, 334 
XtLoseSelectionProc, 321 
XtMainLoop, 344, 434 
XtMakeGeometryRequest, 345, 
347,355 
XtMakeResizeRequest, 357 
XtMalloc, 198, 431 
XtManageChild, 33 
XtManageChildren, 30, 33 
XtMapWidget, 353 
XtMenuPopup, 393 
argument to, 394 
XtMergeArgLists, 97 
XtMoveWidget, 50, 342, 352 
XtN constants, 38 
XtN symbols, see also XmN, 396 
XtNameToWidget, 428 
XtNbaseTranslations, 279 
XtNcolormap, setting, 308 
XtNcreatePopupChildProc 
resource, 408 
XtNcustomization, 433 
XtNew, 431 
XtNewString, 431 
XtNextEvent, 434 
XtNFontSet, 449 
XtNinitiaIResourcesPersistent, 
288 
XtNinput, setting, 306 
XtNmultiClickTime resource, 
217 
XtNsensitive resource, 75 

dex 565 



XtOffsetOf, 83 
XtOffsetOf macro, 258 
XtOpenDisplay, 437, 507 
XtOverrideTranslations, 121 
XtOwnSelection, 313, 320-321 
XtOwnSelectionlncremental, 334 
XtParseAcceleratorTable, 226 
XtParseTranslationTable, 121, 
161,226 
XtPeekEvent, 249, 434 
XtPending, 249, 434 
XtPointer, 284 
XtPopdown, 70, 389, 393 
XtPopup, 70, 389, 401 
XtPopupSpringLoaded, 389 
XtProcedureArg address mode 
constant, 290 
XtProcessEvent, 434 
XtQueryGeometry, 343-344, 346 
XtR resource lists, 81 
XtR symbols, see also XmR, 396 
XtRAcceleratorTable represen- 
tation type, 281 
XTranslateCoordinates Xlib 
function, 398 
XtRBackingStore representation 
type, 286 
XtRBitmap representation type, 
286 
XtRBool representation type, 
281 
XtRBoolean representation type, 
281 
XtRCallback representation 
type, 286 
XtRCalIProc representation 
type, 259, 284 
XtRCursor representation type, 
281,286 
XtRDimension representation 
type, 281 
XtRDisplay representation type, 
281 
XtRealizeWidget, 30, 34, 168, 
342, 344-345,353 
XtRealloc, 431 
XtRegisterCaseConverter, 430 
XtRegisterGrabAction, 389 
XtReleaseGC, 190 
XtRemoveActionHook, 432 
XtRemoveAlICallbacks, warning 
about, 79 

XtRemoveCallback, 79-80, 396 
XtRemoveCallbacks, 79-80 
XtRemoveEventHandler, 198, 
234 
XtRemoveGrab, 409 
XtRemoveInput, 241 
XtRemoveRawEventHandler, 
235 
XtRemoveTimeOut, 198, 244 
XtRemoveWorkProc, 246-247 
XtResizeWidget, 342, 352 
XtResolvePathname, 263,279, 
433 
XtResource, 256 
XtResourceDefaultProc, 
example, 285 
XtResourceList, 256 
XtResourceQuark address mode 
constant, 290 
XtResourceString address mode 
constant, 290 
XtRFile representation type, 281 
XtRFIoat representation type, 
281 
XtRFont representation type, 
281 
XtRFontSet, 449 
XtRFontStruct representation 
type, 281 
XtRFunction representation 
type, 286 
XtRGeometry representation 
type, 281 
XtRGravity representation type, 
286 
XtRImmediate representation 
type, 259, 284 
XtRInitialState representation 
type, 281 
XtRInt representation type, 281 
XtRJustify representation type, 
286 
XtROrientation representation 
type, 286 
XtRPixei representation type, 
282 
XtRPosition representation type, 
282 
XtRShort representation type, 
282 
XtRTranslationTable represen- 
tation type, 282 

566 X Toolkit Intrinsics Programming Manual 
.. 



XtRUnsignedChar representa- 
tion type, 282 
XtRVisual representation type, 
282 
XtRWidget representation type, 
286 
XtScreenOfObject, 428 
XtSelectionCallbackProc, 313, 
334 
XtSelectionDoneIncrProc, 334 
XtSelectionDoneProc, 313 
XtSetArg, 47-49, 96, 108 
XtSetErrorHandler, 434 
XtSetErrorMsgHandler, 434 
XtSetKeyboardFocus, 429 
XtSetLanguageProc. 262, 448 
XtSetSelectionTimeout, 335,434 
XtSetSensitive, 75,408 
XtSetSubvalues, 296 
XtSetTypeConverter, 287-289 
arguments, 287 
XtSetValues, 24, 47, 121, 168, 
171,352, 373 
XtSetValuesFunc, 190 
XtSetWarningHandler, 434 
XtSetWarningMsgHandler, 434 
XtTimeOut, 434 
XtTranslateCoords, 75,396, 398 
XtTranslateKey, 430 
XtTranslateKeycode, 430 
XtUngrabButton, 432 
XtUngrabKey, 432 
XtUngrabKeyboard, 432 
XtUngrabPointer, 387, 432 
XtUnmanageChild, 353 
XtUnmanageChildren, 353 
XtUnmapWidget, 353 
XtVaAppCreateShell, 436 
XtVaApplnitialize, 30, 33,507 
arguments, 33 
fallback resources in, 271 
shell created, 74 
XtVaCreateManagedWidget, 30, 
33, 155,259 
XtVaCreatePopupShell, 74, 384 
XtVaCreateWidget, 30, 61, 
154-155,259 
XtVaGetSubresources, 296 
XtVaGetSubvalues, 296 
XtVaGetValues, 45, 151 
XtVaSetSubvalues, 296 

XtVaSetValues, 45, 151,154, 
179-180, 189-191 
XtVaTypedArg, used with com- 
pound strings, 93 
XtVersion constant, 165 
XtVersionDontCheck constant, 
165 
XtWarning, 434 
XtWarningMsg, 434 
XtWidgetBaseOffset address 
mode constant, 290 
XtWidgetGeometry, 354, 356, 
358 
XtWidgetGeometry structure, 
194-196 
XtWidgetToApplicationContext, 
244 
XtWindow, 190, 415 
XtWindowOfObject. 428 
XtWindowToWidget, 428 
XtWorkProc, 434 
XUSERFILESEARCHPATH. 265, 
267 
XUSERFILESEARCHPATH en i- 
ronment variable. 263 
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By Tom Gaskins 
1st Edition, December 1992 
The world of workstations changed dramatically with 
the release of the X Window System. Users can finally 
count on a consistent interface across almost all makes 
and models of computers. At the same time, graphics 
applications become easily portable. 
Until recently, X supported only 2D graphics. Now, 
however, by means of the PEX extensions to X together 
with the PEXlib applications programming interface, 
native, 3D graphics have come to the X Window System. 
PEXlib allows the programmer to create graphics pro- 
grams of any complexity, and also provides the basis for 
higher-level graphics systems and toolkits. 
The PEXlib Programming Manual is the definitive pro- 
grammer's guide to PEXlib, covering both PEX versions 
5.0 and 5.1. Containing over 200 illustrations and 19 
color plates, it combines a thorough and gentle tutorial 
approach with valuable reference features. Along the 
way, it presents the reader with numerous program- 
ming examples, as well as a library of helpful utility rou- 
tines-all of which are available online. You do not 
need to have prior graphics programming experience in 
order to read this manual. 
Written by Tom Gaskins---the widely recognized 
authority who also authored the O'Reilly and Associates' 
PHIGS Programming Manual--this book is the only 
programming guide to PEXlib you will ever need. 
1154pages, ISBN: 1-56592-028-7 
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By O'Reilly & Associates 
1st Edition, December I992 
The PEXlib Reference Manual is the definitive pro- 
grammer's reference resource for PEXlib, and contains 
complete and succinct reference pages for all the 
callable routines in PEXlib version 5.1. The content of 
the PEXlib Reference Manual stands, with relatively few 
changes, as it was created by the MIT X Consortium. 
The PEXlib Reference manual is a companion volume 
to the O'Reilly and Associates' PEXlib Programming 
Manual, written by Tom Gaskins. The Programming 
Manual is a thorough tutorial guide to PEXlib, and 
includes valuable reference features. Together, these 
books offer the most complete and accessible docu- 
mentation available for PEXlib version 5. l. 
577pages, ISBN: 1-56592-029-5 

SEND E-MAIL QUESTIONS TO IIUT"$(OR, A.COM OR 



II " 

If you want more information about our 
books, or want to know where to buy them, 
we're happy to send it. 
CI Send me a free catalog of titles. 
CI What bookstores in my area carry your 
books (U.S. and Canada only)? 
CI Where can I buy your books outside the 
U.S. and Canada? 
CI Send me information about consulting 
services for documentation or program- 
ming. 
CI Send me information about bundling 
books with my product. 

Name 
Address. 

City 
State, ZIP 
Country 
Phone 
Email Address 



NAME 
COMPANY 
ADDRESS 
CITY 

STATE ZIP 

NO POSTAGE 
NECESSARYIF 
MAILEDIN THE 
UNITED STATES 

BUSINESS REPLY MAIL 

FIRST CLASS MAIL PERMIT NO 80 SEBASTOPOL, CA 

POSTAGE WILL BE PAID BY ADDRESSEE 

O'Reilly & Associates, Inc. 
103 Morris Street Suite A 
Sebastopol CA 95472-9902 

NAME 
COMPANY 
ADDRESS 
CITY 

STATE ZIP 

II 

NO POSTAGE 
NECESSARYIF 
MAILEDIN THE 
UNITED STATES 

BUSINESS REPLY MAIL 

FIRST CLASS MAIL PERMIT NO. 80 SEBASTOPOL, CA 

POSTAGE WILL BE PAID BY ADDRESSEE 
O'Reilly & Associates, Inc. 
103 Morris Street Suite A 
Sebastopol CA 95472-9902 



